igni-extension 0.1.0__py3-none-any.whl

igni_extension/__init__.py

@@ -0,0 +1,78 @@
+"""igni-extension: an extension's process, as its author writes it.
+
+    ext = IgniExtension("acme.example")
+
+    @ext.tool(hints=ToolHints(read_only=True, destructive=False, idempotent=True, open_world=False))
+    async def do_thing() -> str: ...
+
+    ext.run()
+
+See the package README for the whole surface.
+"""
+
+from igni_extension.caller import Caller, CallerKind, NoCaller
+from igni_extension.environment import (
+    Assets,
+    ExtensionEnvironment,
+    HostEndpoint,
+    Secrets,
+    Workspace,
+    WorkspaceMode,
+)
+from igni_extension.errors import (
+    HostError,
+    HostErrorCode,
+    HostUnavailable,
+    IgniExtensionError,
+    NotConfigured,
+    NotSignedIn,
+)
+from igni_extension.extension import IgniExtension, ToolNames
+from igni_extension.hints import ToolHints, ToolHintsMissing
+from igni_extension.hooks import Allow, HookEvent, Hooks, Modify, Reject
+from igni_extension.host import Host, Notifications
+from igni_extension.host_model import SCHEMA_VERSION
+from igni_extension.members import Property, Signal
+from igni_extension.notifications import LocalNotification, Target
+from igni_extension.prompt import PromptConditions
+from igni_extension.service import ServiceClient
+from igni_extension.service_events import ServiceEvent
+from igni_extension.tokens import SignedIn
+
+__all__ = [
+    "Allow",
+    "Assets",
+    "Caller",
+    "CallerKind",
+    "ExtensionEnvironment",
+    "Host",
+    "HostEndpoint",
+    "HostError",
+    "HostErrorCode",
+    "HookEvent",
+    "Hooks",
+    "HostUnavailable",
+    "IgniExtension",
+    "IgniExtensionError",
+    "LocalNotification",
+    "Modify",
+    "NoCaller",
+    "NotConfigured",
+    "NotSignedIn",
+    "Notifications",
+    "PromptConditions",
+    "Reject",
+    "Property",
+    "SCHEMA_VERSION",
+    "Secrets",
+    "ServiceClient",
+    "ServiceEvent",
+    "Signal",
+    "SignedIn",
+    "Target",
+    "ToolNames",
+    "ToolHints",
+    "ToolHintsMissing",
+    "Workspace",
+    "WorkspaceMode",
+]

igni_extension/caller.py

@@ -0,0 +1,226 @@
+"""Who a call is for: `Caller`.
+
+Every request igni sends this process — a tool call, a page's call, a
+hook — names the producer it is for: a person (with their organisation
+and the one group they belong to) or an app. A tool or hook handler that wants it declares a
+parameter typed `Caller`, and the SDK passes it in; anything running
+inside that call can also ask `Caller.current()`.
+
+    @ext.tool(hints=ToolHints(read_only=True, destructive=False, idempotent=True, open_world=False))
+    async def mine(caller: Caller) -> list[str]:
+        response = await ext.service.for_(caller).get("/v1/things")
+        ...
+
+A tool typed `caller: Caller` fails when igni sent no caller; one typed
+`caller: Caller | None` runs with `None` instead.
+
+The extension never decides who may call it: igni only forwards a call
+the producer may make. Its job is to serve the caller it is handed — and
+to keep callers apart, which is why the caller lives in the request, not
+in a global. Concurrent calls each see their own (`contextvars`), and a
+plain `def` running in a worker thread sees its call's caller too.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import inspect
+from collections.abc import Callable, Iterator
+from contextvars import ContextVar
+from enum import StrEnum
+from functools import wraps
+from typing import Any, ClassVar, get_type_hints
+
+from mcp.server.context import CallNext, HandlerResult, ServerRequestContext
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+
+class CallerKind(StrEnum):
+    PERSON = "person"
+    APP = "app"
+    #: One end user of an app, a producer of its own.
+    SPACE = "space"
+
+
+class NoCaller(LookupError):
+    """Asked for the caller outside a call igni made: in `on_start` work, say."""
+
+
+class Caller(BaseModel):
+    """The producer one call is for."""
+
+    model_config = ConfigDict(frozen=True)
+
+    #: Where the host puts it: the MCP request's `_meta` key, and the hook frame's field.
+    META_KEY: ClassVar[str] = "igni/principal"
+    #: How a token request names whom the token is for.
+    TOKEN_HEADER: ClassVar[str] = "X-Igni-Principal"  # noqa: S105 — a header's name, not a secret
+
+    kind: CallerKind
+    #: The person's or the app's id on igni server.
+    id: str
+    #: Their organisation.
+    org: str | None = None
+    #: The one group a person belongs to in `org`; an app has none.
+    group: str | None = None
+    #: The igni session the call comes from, when there is one.
+    session: str | None = None
+    #: A space's app (its id); `None` for a person or an app.
+    app: str | None = None
+    #: The app's own name for a space's end user.
+    external_id: str | None = None
+
+    @property
+    def ref(self) -> str:
+        """`person:<id>` — how the host's token endpoint is told whom a token is for."""
+        return f"{self.kind.value}:{self.id}"
+
+    @classmethod
+    def of(cls, raw: Any) -> Caller | None:
+        """A caller from the wire, or `None` when there is none or it is malformed."""
+        if not isinstance(raw, dict):
+            return None
+        try:
+            return cls.model_validate(raw)
+        except ValidationError:
+            return None
+
+    @classmethod
+    def current(cls) -> Caller | None:
+        """The caller of the call being served now, or `None` outside one."""
+        scoped = _SCOPE.get()
+        if scoped is not None:
+            return scoped
+        meta = RequestMeta.current()
+        return cls.of(meta.get(cls.META_KEY)) if meta is not None else None
+
+    @classmethod
+    def required(cls) -> Caller:
+        """The current caller; `NoCaller` outside a call igni made."""
+        caller = cls.current()
+        if caller is None:
+            raise NoCaller(
+                "no caller: this runs outside a call igni made, or igni sent none. "
+                "Work with no caller uses the service as the extension itself."
+            )
+        return caller
+
+
+#: The caller of the call being served, where the SDK set it itself (a hook).
+_SCOPE: ContextVar[Caller | None] = ContextVar("igni_caller", default=None)
+
+#: The `_meta` of the MCP request being served, set by `RequestMeta.middleware`.
+_META: ContextVar[dict[str, Any] | None] = ContextVar("igni_request_meta", default=None)
+
+
+class RequestMeta:
+    """The `_meta` of the MCP request this code is serving, wherever it runs.
+
+    Set for the length of each request by `middleware`, which the
+    extension's server runs on every message igni sends, so a tool — and
+    anything it calls, on the loop or in a worker thread — reads the
+    request it serves: concurrent calls each see their own.
+    """
+
+    @staticmethod
+    def current() -> dict[str, Any] | None:
+        """The current request's `_meta`, or `None` outside a request (or when it had none)."""
+        return _META.get()
+
+    @staticmethod
+    async def middleware(ctx: ServerRequestContext[Any, Any], call_next: CallNext) -> HandlerResult:
+        """An MCP server middleware: the request's `_meta` is current while it is served."""
+        token = _META.set(dict(ctx.meta) if ctx.meta else None)
+        try:
+            return await call_next(ctx)
+        finally:
+            _META.reset(token)
+
+
+class CallerScope:
+    """Sets the caller for the call being served, and finds where a function wants it."""
+
+    @staticmethod
+    @contextlib.contextmanager
+    def of(caller: Caller | None) -> Iterator[None]:
+        token = _SCOPE.set(caller)
+        try:
+            yield
+        finally:
+            _SCOPE.reset(token)
+
+    @staticmethod
+    def parameter(fn: Callable[..., Any]) -> str | None:
+        """The name of `fn`'s parameter typed `Caller` (or `Caller | None`), if it has one."""
+        try:
+            hints = get_type_hints(fn)
+        except (NameError, TypeError):
+            hints = getattr(fn, "__annotations__", {})
+        for name, annotation in hints.items():
+            if name != "return" and annotation in (Caller, Caller | None):
+                return name
+        return None
+
+    @staticmethod
+    def optional(fn: Callable[..., Any], name: str) -> bool:
+        """Whether `fn` takes `Caller | None` there: it runs without one, rather than failing."""
+        try:
+            return bool(get_type_hints(fn).get(name) == Caller | None)
+        except (NameError, TypeError):
+            return False
+
+    @classmethod
+    def inject(cls, fn: Callable[..., Any]) -> Callable[..., Any]:
+        """`fn` with its `Caller` parameter filled from the call, and hidden from its schema.
+
+        The parameter is not something igni or a model supplies, so it
+        is not part of the tool's input: the wrapper's signature leaves
+        it out, and the schema derived from it does too.
+        """
+        name = cls.parameter(fn)
+        if name is None:
+            return fn
+        find: Callable[[], Caller | None] = (
+            Caller.current if cls.optional(fn, name) else Caller.required
+        )
+        signature = inspect.signature(fn)
+        # Resolved now, against the author's module: the wrapper lives in
+        # this one, and a string annotation evaluated here would not find
+        # the author's types.
+        try:
+            resolved = get_type_hints(fn)
+        except (NameError, TypeError):
+            resolved = dict(getattr(fn, "__annotations__", {}))
+        visible = [
+            p.replace(annotation=resolved.get(p.name, p.annotation))
+            for p in signature.parameters.values()
+            if p.name != name
+        ]
+        hints = {k: v for k, v in resolved.items() if k != name}
+        return_annotation = resolved.get("return", signature.return_annotation)
+
+        if inspect.iscoroutinefunction(fn):
+
+            @wraps(fn)
+            async def with_caller_async(*args: Any, **kwargs: Any) -> Any:
+                return await fn(*args, **kwargs, **{name: find()})
+
+            wrapper: Callable[..., Any] = with_caller_async
+        else:
+
+            @wraps(fn)
+            def with_caller(*args: Any, **kwargs: Any) -> Any:
+                return fn(*args, **kwargs, **{name: find()})
+
+            wrapper = with_caller
+        wrapper.__signature__ = signature.replace(  # type: ignore[attr-defined]
+            parameters=visible, return_annotation=return_annotation
+        )
+        wrapper.__annotations__ = hints
+        # `wraps` points `__wrapped__` at `fn`, and `inspect.signature`
+        # follows it back to the hidden parameter.
+        del wrapper.__wrapped__  # type: ignore[attr-defined]
+        return wrapper
+
+
+__all__ = ["Caller", "CallerKind", "CallerScope", "NoCaller", "RequestMeta"]

igni_extension/channel.py

@@ -0,0 +1,295 @@
+"""The socket to the igni host: how `ext.host` reaches igni.
+
+igni starts an extension's process with `IGNI_HOST_URL` and
+`IGNI_HOST_SECRET`: a WebSocket on the host's loopback interface and the
+secret that says which process this is. Every `get`, `set` and `call` on
+`ext.host` is one request on it, and every signal the extension handles
+arrives on it. The protocol is igni's `docs/HOST_MODEL_PROTOCOL.md`; an
+extension author never sees it.
+
+Started without those variables — run outside igni, or by an igni older
+than the host model — `ext.host` raises `NotConfigured`, except
+`ext.host.notifications.notify`, which then travels as the MCP
+notification igni has always understood.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import itertools
+import json
+import logging
+import os
+from typing import Any
+
+from websockets.asyncio.client import ClientConnection, connect
+from websockets.exceptions import WebSocketException
+
+from igni_extension.environment import HostEndpoint
+from igni_extension.errors import HostError, HostUnavailable, NotConfigured
+from igni_extension.hooks import HookHandlers
+from igni_extension.notifications import LocalNotification, NotifyNotification
+from igni_extension.service_events import SERVICE_EVENT, ServiceEventHandlers
+from igni_extension.session import HostSession
+from igni_extension.signals import SignalHandlers
+
+logger = logging.getLogger(__name__)
+
+#: The one member that still works without the socket.
+NOTIFY = "notifications.notify"
+
+
+#: Members whose answer is the person's, so no timeout applies to them.
+WAITS_ON_THE_PERSON = frozenset({"ui.show_dialog"})
+
+
+class HostConnection:
+    """One extension process's connection to the igni host."""
+
+    #: How long a request waits for its answer.
+    TIMEOUT = 120.0
+    #: Between attempts to reach a host that is not answering yet.
+    RETRY_SECONDS = 2.0
+
+    def __init__(
+        self,
+        endpoint: HostEndpoint,
+        signals: SignalHandlers,
+        session: HostSession | None = None,
+        hooks: HookHandlers | None = None,
+        service_events: ServiceEventHandlers | None = None,
+    ) -> None:
+        self._endpoint = endpoint
+        self._signals = signals
+        self._hooks = hooks if hooks is not None else HookHandlers()
+        self._service_events = (
+            service_events if service_events is not None else ServiceEventHandlers()
+        )
+        self._session = session
+        self._socket: ClientConnection | None = None
+        self._reader: asyncio.Task[None] | None = None
+        self._lock = asyncio.Lock()
+        self._ids = itertools.count(1)
+        self._waiting: dict[int, asyncio.Future[Any]] = {}
+        self._hello: asyncio.Future[dict[str, Any]] | None = None
+        self._tasks: set[asyncio.Task[Any]] = set()
+        #: What the host said this extension holds, after connecting.
+        self.granted: list[str] = []
+        self.schema_version = ""
+        signals.when_new(self._new_signal)
+
+    @property
+    def configured(self) -> bool:
+        return self._endpoint.configured
+
+    @property
+    def connected(self) -> bool:
+        return self._socket is not None
+
+    # ── HostLink ──────────────────────────────────────────────────
+
+    async def request(
+        self,
+        op: str,
+        path: str,
+        *,
+        window: str | None = None,
+        session: str | None = None,
+        params: dict[str, Any] | None = None,
+        value: Any = None,
+    ) -> Any:
+        if not self.configured:
+            if op == "call" and path == NOTIFY and self._session is not None:
+                notification = LocalNotification.model_validate((params or {})["notification"])
+                await self._session.send(NotifyNotification.of(notification))
+                return None
+            raise NotConfigured(
+                f"host.{path}: igni did not give this process the host's address "
+                "(IGNI_HOST_URL, IGNI_HOST_SECRET) — it is not running inside igni"
+            )
+        await self.connect()
+        body: dict[str, Any] = {"op": op, "path": path}
+        if window is not None:
+            body["window"] = window
+        if session is not None:
+            body["session"] = session
+        if params:
+            body["params"] = params
+        if op == "set":
+            body["value"] = value
+        return await self._send(body)
+
+    # ── The socket ────────────────────────────────────────────────
+
+    def _headers(self) -> dict[str, str]:
+        """The secret, and — where there is one — this process's group.
+
+        igni ends the group if the process hangs and it has to restart
+        it; it checks that it started the group's leader first.
+        """
+        headers = {"Authorization": f"Bearer {self._endpoint.secret}"}
+        if hasattr(os, "getpgid"):
+            headers["X-Igni-Process-Group"] = str(os.getpgid(0))
+        return headers
+
+    async def connect(self) -> None:
+        """Connect and say which signals are handled. Idempotent."""
+        async with self._lock:
+            if self._socket is not None:
+                return
+            try:
+                socket = await connect(
+                    self._endpoint.url,
+                    additional_headers=self._headers(),
+                    max_size=8 * 1024 * 1024,
+                    compression=None,
+                )
+            except (OSError, WebSocketException) as exc:
+                raise HostUnavailable(f"the igni host did not answer: {exc}") from exc
+            self._socket = socket
+            loop = asyncio.get_running_loop()
+            self._hello = loop.create_future()
+            self._reader = asyncio.create_task(self._read(socket))
+            try:
+                hello = await asyncio.wait_for(asyncio.shield(self._hello), self.TIMEOUT)
+            except TimeoutError as exc:
+                await self._drop()
+                raise HostUnavailable("the igni host did not say hello") from exc
+            self.granted = list(hello.get("granted") or [])
+            self.schema_version = str(hello.get("schema_version") or "")
+        wires = self._signals.wires()
+        if wires:
+            await self._subscribe(wires)
+
+    async def serve_forever(self) -> None:
+        """Stay connected while the process runs, so signals keep arriving."""
+        if not self.configured:
+            return
+        while True:
+            try:
+                await self.connect()
+            except HostUnavailable as exc:
+                logger.debug("igni: %s; trying again", exc)
+                await asyncio.sleep(self.RETRY_SECONDS)
+                continue
+            reader = self._reader
+            if reader is not None:
+                with contextlib.suppress(Exception):
+                    await asyncio.shield(reader)
+            await asyncio.sleep(self.RETRY_SECONDS)
+
+    async def close(self) -> None:
+        await self._drop()
+        for task in list(self._tasks):
+            task.cancel()
+
+    async def _send(self, body: dict[str, Any]) -> Any:
+        socket = self._socket
+        if socket is None:
+            raise HostUnavailable("not connected to the igni host")
+        request_id = next(self._ids)
+        future: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
+        self._waiting[request_id] = future
+        try:
+            await socket.send(json.dumps({"id": request_id, **body}))
+            # A dialog waits on the person, for as long as they take.
+            limit = None if body.get("path") in WAITS_ON_THE_PERSON else self.TIMEOUT
+            reply = await asyncio.wait_for(future, limit)
+        except (OSError, WebSocketException) as exc:
+            raise HostUnavailable(f"the igni host went away: {exc}") from exc
+        except TimeoutError as exc:
+            raise HostUnavailable(f"host.{body.get('path')} got no answer") from exc
+        finally:
+            self._waiting.pop(request_id, None)
+        if reply.get("ok"):
+            return reply.get("result")
+        error = reply.get("error") or {}
+        raise HostError(str(error.get("code") or "failed"), str(error.get("message") or "refused"))
+
+    async def _subscribe(self, wires: list[str]) -> None:
+        outcome = await self._send({"op": "subscribe", "signals": wires})
+        if isinstance(outcome, dict):
+            for wire in outcome.get("not_granted") or []:
+                logger.warning(
+                    "igni: %s will never arrive — its object is not in permissions.host", wire
+                )
+            for wire in outcome.get("unknown") or []:
+                logger.warning("igni: this igni has no signal %s", wire)
+
+    def _new_signal(self, wire: str) -> None:
+        if self._socket is None:
+            return  # sent with the rest on connect
+        self._spawn(self._subscribe([wire]))
+
+    async def _read(self, socket: ClientConnection) -> None:
+        try:
+            async for raw in socket:
+                try:
+                    message = json.loads(raw)
+                except ValueError:
+                    continue
+                op = message.get("op")
+                if op == "hello" and self._hello is not None and not self._hello.done():
+                    self._hello.set_result(message)
+                elif op == "reply":
+                    waiter = self._waiting.get(message.get("id"))
+                    if waiter is not None and not waiter.done():
+                        waiter.set_result(message)
+                elif op == "signal":
+                    # A task, not an await: a handler that reads the model
+                    # needs this loop free to receive the answer.
+                    self._spawn(
+                        self._signals.deliver(str(message.get("signal")), message.get("value"))
+                    )
+                elif op == "hook":
+                    # Off the read loop, as a signal is handled; igni
+                    # waits on a deciding one, against a deadline.
+                    hook_id = message.get("id")
+                    name = str(message.get("event"))
+                    principal = message.get("principal")
+                    if hook_id is None:
+                        self._spawn(self._hooks.tell(name, message.get("value"), principal))
+                    else:
+                        self._spawn(
+                            self._answer(str(hook_id), name, message.get("value"), principal)
+                        )
+        except WebSocketException:
+            pass
+        finally:
+            if self._socket is socket:
+                self._socket = None
+            for waiter in self._waiting.values():
+                if not waiter.done():
+                    waiter.set_exception(HostUnavailable("the igni host went away"))
+
+    async def _answer(self, hook_id: str, event: str, value: Any, principal: Any = None) -> None:
+        if event == SERVICE_EVENT:
+            params = await self._service_events.answer(hook_id, value, principal)
+        else:
+            params = await self._hooks.answer(hook_id, event, value, principal)
+        try:
+            await self._send({"op": "answer", "params": params})
+        except (HostError, HostUnavailable) as exc:
+            # Too late, or the host went away: the event went ahead or not
+            # without this answer, as igni decides for a silence.
+            logger.warning("igni: the answer to %s did not count: %s", event, exc)
+
+    async def _drop(self) -> None:
+        socket, self._socket = self._socket, None
+        if socket is not None:
+            with contextlib.suppress(Exception):
+                await socket.close()
+        if self._reader is not None:
+            self._reader.cancel()
+            with contextlib.suppress(BaseException):
+                await self._reader
+            self._reader = None
+
+    def _spawn(self, coro: Any) -> None:
+        task = asyncio.create_task(coro)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+
+
+__all__ = ["HostConnection"]

igni_extension/clock.py

@@ -0,0 +1,12 @@
+"""Time, as one object, so tests can move it."""
+
+from __future__ import annotations
+
+import time
+
+
+class Clock:
+    """The system's monotonic clock: a token's age is measured on it."""
+
+    def monotonic(self) -> float:
+        return time.monotonic()