toolframe-core 0.6.2__py3-none-any.whl

toolframe_core/config.py

@@ -0,0 +1,267 @@
+"""TOML is desired state. Every managed edit is revision checked and atomically replaced."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import secrets
+import tempfile
+import uuid
+from pathlib import Path
+from typing import Literal
+from urllib.parse import urlsplit
+
+import tomlkit
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from toolframe_sdk import PluginError
+
+from .network import bind_host
+
+
+def validate_plugin_id(identifier: str) -> str:
+    if not re.fullmatch(r"[a-z][a-z0-9-]{0,63}", identifier):
+        raise ValueError(
+            "Plugin IDs must be normalized lowercase slugs (1–64 characters)"
+        )
+    return identifier
+
+
+class Model(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class Application(Model):
+    id: str
+    name: str = "Toolframe"
+    host: str = "127.0.0.1"
+    port: int = Field(default=9876, ge=0, le=65535)
+    public_url: str = ""
+
+    @field_validator("public_url")
+    @classmethod
+    def public_origin(cls, value):
+        if not value:
+            return ""
+        uri = urlsplit(value)
+        if (
+            not uri.hostname
+            or uri.username
+            or uri.password
+            or uri.path not in {"", "/"}
+            or uri.query
+            or uri.fragment
+            or uri.port == 0
+            or (
+                uri.scheme != "https"
+                and not (
+                    uri.scheme == "http"
+                    and uri.hostname in {"localhost", "127.0.0.1", "::1"}
+                )
+            )
+        ):
+            raise ValueError(
+                "public_url must be an HTTPS origin or HTTP loopback origin"
+            )
+        return value.rstrip("/")
+
+    @field_validator("host")
+    @classmethod
+    def listen_address(cls, value):
+        return bind_host(value)
+
+
+class PluginRequest(Model):
+    source: str
+    enabled: bool = False
+    watch: bool = False
+    config: dict = Field(default_factory=dict)
+
+
+class RuntimeSettings(Model):
+    drain_timeout: float = Field(default=30, gt=0)
+    activation_timeout: float = Field(default=30, gt=0)
+    max_task_timeout: float = Field(default=3600, ge=30, le=86400, allow_inf_nan=False)
+    disposal_timeout: float = Field(default=10, gt=0)
+    health_interval: float = Field(default=10, gt=0)
+    health_ttl: float = Field(default=30, gt=0)
+    watch_debounce_ms: int = Field(default=500, ge=50)
+
+    @field_validator("max_task_timeout", mode="before")
+    @classmethod
+    def task_timeout_policy(cls, value):
+        if isinstance(value, bool):
+            raise ValueError("max_task_timeout must be a number of seconds")  # noqa: TRY004 - Pydantic validators report ValueError as validation failures
+        return value
+
+
+class PackageSettings(Model):
+    find_links: list[str] = Field(default_factory=list)
+    index_url: str = "https://pypi.org/simple"
+    offline: bool = False
+
+
+class AccessPolicy(Model):
+    mode: Literal["public", "protected"] = "public"
+    local_control: bool = True
+    auth_provider: str = "auth"
+    dashboard_auth: str = "dashboard-auth"
+    oidc_provider: str = ""
+    # Retain the historical interpretation of existing files without this field.
+    # New applications write an explicit closed policy during initialization.
+    failure_mode: Literal["public", "closed"] = "public"
+
+    @field_validator("oidc_provider")
+    @classmethod
+    def oidc_identity(cls, value):
+        return validate_plugin_id(value) if value else ""
+
+    @field_validator("auth_provider", "dashboard_auth")
+    @classmethod
+    def identities(cls, value):
+        return validate_plugin_id(value)
+
+
+class McpAccessPolicy(Model):
+    mode: Literal["public", "protected"] = "public"
+    auth_provider: str = "mcp-auth"
+
+    @field_validator("auth_provider")
+    @classmethod
+    def identity(cls, value):
+        return validate_plugin_id(value)
+
+
+class Composition(Model):
+    schema_version: Literal[1] = 1
+    application: Application
+    plugins: dict[str, PluginRequest] = Field(default_factory=dict)
+    bindings: dict[str, str] = Field(default_factory=dict)
+    required_capabilities: list[str] = Field(default_factory=list)
+    runtime: RuntimeSettings = Field(default_factory=RuntimeSettings)
+    packages: PackageSettings = Field(default_factory=PackageSettings)
+    access: AccessPolicy = Field(default_factory=AccessPolicy)
+    mcp_access: McpAccessPolicy = Field(default_factory=McpAccessPolicy)
+
+    @field_validator("plugins")
+    @classmethod
+    def plugin_ids(cls, value):
+        for identifier in value:
+            validate_plugin_id(identifier)
+        return value
+
+
+def atomic_write(path: Path, content: str, *, mode=0o600):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "w") as handle:
+            os.fchmod(handle.fileno(), mode)
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+        directory = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+class ConfigFile:
+    def __init__(self, home: Path):
+        self.home = home.resolve()
+        self.path = self.home / "toolframe.toml"
+
+    @property
+    def revision(self):
+        return (
+            hashlib.sha256(self.path.read_bytes()).hexdigest()
+            if self.path.exists()
+            else None
+        )
+
+    def read(self):
+        try:
+            text = self.path.read_text()
+            document = tomlkit.parse(text)
+            return Composition.model_validate(document.unwrap()), hashlib.sha256(
+                text.encode()
+            ).hexdigest()
+        except (OSError, ValueError) as error:
+            raise PluginError("configuration_invalid", str(error)) from error
+
+    def initialize(self, *, name="Toolframe", host="127.0.0.1", port=9876):
+        if self.path.exists():
+            raise PluginError(
+                "configuration_exists", "Refusing to overwrite existing toolframe.toml"
+            )
+        value = Composition(
+            application=Application(
+                id=str(uuid.uuid4()), name=name, host=host, port=port
+            ),
+            access=AccessPolicy(failure_mode="closed"),
+        )
+        atomic_write(self.path, tomlkit.dumps(value.model_dump()))
+        return value
+
+    def edit(self, expected_revision, change):
+        if self.revision != expected_revision:
+            raise PluginError("stale_plan", "toolframe.toml changed after planning")
+        document = tomlkit.parse(self.path.read_text())
+        change(document)
+        value = Composition.model_validate(document.unwrap())
+        # Recheck immediately before rename; host lock serializes managed writers.
+        if self.revision != expected_revision:
+            raise PluginError(
+                "stale_plan", "toolframe.toml changed while applying the edit"
+            )
+        atomic_write(self.path, tomlkit.dumps(document))
+        return value, self.revision
+
+    def put_plugin(self, identifier, request, expected_revision):
+        def change(document):
+            if "plugins" not in document:
+                document["plugins"] = tomlkit.table()
+            document["plugins"][identifier] = request.model_dump()
+
+        return self.edit(expected_revision, change)
+
+
+class HostLock:
+    def __init__(self, home):
+        self.path = Path(home) / ".toolframe" / "host.lock"
+        self.file = None
+
+    def acquire(self):
+        import fcntl
+
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.file = self.path.open("a+")
+        try:
+            fcntl.flock(self.file, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as error:
+            self.file.close()
+            self.file = None
+            raise PluginError(
+                "host_already_running", "Another core owns this application home"
+            ) from error
+        self.file.seek(0)
+        self.file.truncate()
+        self.file.write(str(os.getpid()))
+        self.file.flush()
+
+    def close(self):
+        if self.file:
+            self.file.close()
+            self.file = None
+
+
+def management_token(home):
+    path = Path(home) / ".toolframe" / "management.token"
+    if not path.exists():
+        atomic_write(path, secrets.token_urlsafe(32))
+    return path.read_text().strip()

toolframe_core/diagnostics.py

@@ -0,0 +1,200 @@
+"""Read-only topology from selected definitions and the lifecycle planner.
+
+Never import plugin code or prepare candidates here. Inactive declarations are
+useful for diagnosis, but must not replace the running graph with a newer wheel.
+"""
+
+from toolframe_sdk import PluginDefinition
+
+from .graph import Graph
+
+PRESENTATIONS = {
+    "dashboard.page": "dashboard",
+    "mcp.tool": "mcp",
+    "llms.document": "llms",
+}
+
+
+def dependency_snapshot(graph, plugins, candidates, bindings, cordis, publication):
+    definitions = {
+        name: PluginDefinition.model_validate(candidate["definition"])
+        for name, candidate in candidates.items()
+        if name not in graph.definitions
+    }
+    definitions.update(graph.definitions)
+    lifecycle = {item["name"]: item for item in cordis}
+    nodes, edges = [], []
+    for item in plugins:
+        name = item["id"]
+        definition = definitions.get(name)
+        selected = name in graph.definitions
+        observed = lifecycle.get(name, {})
+        state = observed.get("state", item["runtime"].get("state", "installed"))
+        if not selected:
+            if item["desired"].get("installed") is False:
+                state = "removed"
+            elif item["stopped_override"]:
+                state = "stopped"
+            elif not item["desired"].get("enabled", False):
+                state = "disabled"
+        candidate = graph.candidates.get(name, candidates.get(name, {}))
+        nodes.append(
+            {
+                "id": name,
+                "label": name,
+                "kind": definition.kind if definition else "unknown",
+                "provider_kind": definition.provider_kind if definition else None,
+                "version": candidate.get("version"),
+                "state": state,
+                "healthy": item["healthy"],
+                "health_fresh": item["health_fresh"],
+                "enabled": item["desired"].get("enabled", False),
+                "selected": selected,
+                "definition_source": "selected"
+                if selected
+                else "last_candidate"
+                if definition
+                else "unavailable",
+                "in_flight": observed.get("inFlight", 0),
+                "blocked_by": observed.get("blockedBy", item["blocked_by"]),
+            }
+        )
+        if not definition:
+            continue
+        for alias, requirement in sorted(definition.requires.items()):
+            resolved = graph.bindings.get(name, {}).get(alias) if selected else None
+            # For an unresolved/inactive declaration, show a known supplier only
+            # if unambiguous. This is not a new runtime binding.
+            explicit = bindings.get(
+                f"{name}/{alias}", bindings.get(requirement.service)
+            )
+            matches = [
+                owner
+                for owner, target in definitions.items()
+                if requirement.service in target.services
+                and target.services[requirement.service].version == requirement.version
+                and (not explicit or owner == explicit)
+            ]
+            target = (
+                resolved[0] if resolved else matches[0] if len(matches) == 1 else None
+            )
+            state = "resolved" if resolved else "missing" if selected else "inactive"
+            if target is None:
+                target = f"requirement:{name}:{alias}"
+                nodes.append(
+                    {
+                        "id": target,
+                        "label": f"{requirement.service} v{requirement.version}",
+                        "kind": "unresolved",
+                        "state": "ambiguous" if len(matches) > 1 else "missing",
+                    }
+                )
+            edges.append(
+                {
+                    "source": name,
+                    "target": target,
+                    "kind": "optional" if requirement.optional else "required",
+                    "label": f"{requirement.service} v{requirement.version}",
+                    "alias": alias,
+                    "state": state,
+                }
+            )
+        for resource_kind, provider_kind in PRESENTATIONS.items():
+            resources = sorted(
+                resource.id
+                for resource in definition.resources
+                if resource.kind == resource_kind
+            )
+            if not resources:
+                continue
+            target = graph.providers.get(provider_kind)
+            if target is None:
+                matches = [
+                    owner
+                    for owner, target_definition in definitions.items()
+                    if target_definition.provider_kind == provider_kind
+                ]
+                target = (
+                    matches[0] if len(matches) == 1 else f"provider:{provider_kind}"
+                )
+                if target.startswith("provider:") and not any(
+                    node["id"] == target for node in nodes
+                ):
+                    nodes.append(
+                        {
+                            "id": target,
+                            "label": f"{provider_kind} provider",
+                            "kind": "unresolved",
+                            "state": "missing",
+                        }
+                    )
+            edges.append(
+                {
+                    "source": name,
+                    "target": target,
+                    "kind": "presentation",
+                    "label": resource_kind,
+                    "resources": resources,
+                    "state": "inactive"
+                    if not selected
+                    else "resolved"
+                    if target in graph.definitions
+                    else "missing",
+                    "publication": publication.get(provider_kind, {}).get(
+                        "state", "unavailable"
+                    ),
+                }
+            )
+    impacts = {}
+    for name in sorted(graph.definitions):
+        impacts[name] = {}
+        for action in ("reload", "disable"):
+            replacement = (
+                graph
+                if action == "reload"
+                else Graph(
+                    {
+                        key: value
+                        for key, value in graph.candidates.items()
+                        if key != name
+                    },
+                    graph.binding_preferences,
+                )
+            )
+            affected = graph.affected(replacement, {name})
+            dependents = graph.dependents({name}) - {name}
+            presentations = [
+                {
+                    "owner": edge["source"],
+                    "provider": edge["target"],
+                    "kind": edge["label"],
+                    "resources": edge["resources"],
+                }
+                for edge in edges
+                if edge["kind"] == "presentation"
+                and edge["source"] in graph.definitions
+                and (edge["source"] in affected or edge["target"] in affected)
+            ]
+            impacts[name][action] = {
+                "affected": sorted(affected),
+                "required_dependents": sorted(dependents),
+                "presentation_providers": sorted(affected - dependents - {name}),
+                "optional_consumers": sorted(
+                    owner
+                    for owner, resolved in graph.bindings.items()
+                    if owner not in affected
+                    and any(
+                        target in affected
+                        and graph.definitions[owner].requires[alias].optional
+                        for alias, (target, _) in resolved.items()
+                    )
+                ),
+                "presentations": presentations,
+            }
+    return {
+        "schema_version": 1,
+        "basis": "selected",
+        "nodes": sorted(nodes, key=lambda node: node["id"]),
+        "edges": edges,
+        "impacts": impacts,
+    }

toolframe_core/graph.py

@@ -0,0 +1,207 @@
+"""Resolve explicit service identities independently of presentation attachment."""
+
+from graphlib import CycleError, TopologicalSorter
+
+from toolframe_sdk import OwnedResource, PluginDefinition, PluginError, digest
+
+
+class Graph:
+    def __init__(self, candidates, bindings):
+        self.candidates = candidates
+        self.binding_preferences = dict(bindings)
+        self.definitions = {
+            name: PluginDefinition.model_validate(value["definition"])
+            for name, value in candidates.items()
+        }
+        self.dependencies = {name: set() for name in candidates}
+        self.bindings = {}
+        self.missing = {}
+        self.providers = {}
+        self.storage_providers = set()
+        self.stores = {}
+        for name, definition in self.definitions.items():
+            if definition.provider_kind == "storage":
+                self.storage_providers.add(name)
+            elif definition.provider_kind:
+                if definition.provider_kind in self.providers:
+                    raise PluginError(
+                        "provider_conflict",
+                        f"Only one enabled {definition.provider_kind} provider can own its routes/store",
+                    )
+                self.providers[definition.provider_kind] = name
+        for name, definition in self.definitions.items():
+            resolved = self.bindings[name] = {}
+            missing = self.missing[name] = []
+            for alias, requirement in definition.requires.items():
+                matches = [
+                    owner
+                    for owner, target in self.definitions.items()
+                    if requirement.service in target.services
+                    and target.services[requirement.service].version
+                    == requirement.version
+                ]
+                explicit = bindings.get(
+                    f"{name}/{alias}", bindings.get(requirement.service)
+                )
+                if explicit:
+                    matches = [owner for owner in matches if owner == explicit]
+                if len(matches) > 1:
+                    raise PluginError(
+                        "service_ambiguous",
+                        f"Bind {name}/{alias} explicitly; several plugins provide {requirement.service}",
+                    )
+                if not matches:
+                    if not requirement.optional:
+                        missing.append(requirement.service)
+                    continue
+                resolved[alias] = (matches[0], requirement.service)
+                if not requirement.optional:
+                    self.dependencies[name].add(matches[0])
+            sql_requirements = {
+                alias: requirement
+                for alias, requirement in definition.requires.items()
+                if requirement.service == "toolframe.storage.sql"
+            }
+            if definition.store and not any(
+                not requirement.optional for requirement in sql_requirements.values()
+            ):
+                raise PluginError(
+                    "invalid_store_dependency",
+                    "A managed store requires a non-optional SQL storage dependency",
+                    {"owner": name},
+                )
+            storage = {
+                resolved[alias][0] for alias in sql_requirements if alias in resolved
+            }
+            if len(storage) > 1:
+                raise PluginError(
+                    "multiple_store_providers",
+                    "Each plugin may bind its SQL store to only one provider",
+                    {"owner": name, "providers": sorted(storage)},
+                )
+            if storage:
+                provider = next(iter(storage))
+                if provider not in self.storage_providers:
+                    raise PluginError(
+                        "invalid_storage_provider",
+                        "The SQL service must be supplied by a storage provider",
+                        {"owner": name, "provider": provider},
+                    )
+                self.stores[name] = provider
+            for resource in definition.resources:
+                if resource.kind == "mcp.tool":
+                    service = resource.data["service"]
+                    if service in definition.services:
+                        target = definition.services[service]
+                    else:
+                        matching = [
+                            alias
+                            for alias, item in definition.requires.items()
+                            if item.service == service
+                        ]
+                        if not matching:
+                            raise PluginError(
+                                "resource_target_invalid",
+                                f"{name}/{resource.id} targets an undeclared service",
+                            )
+                        resolution = resolved.get(matching[0])
+                        target = (
+                            self.definitions[resolution[0]].services[service]
+                            if resolution
+                            else None
+                        )
+                    if target and resource.data["method"] not in target.methods:
+                        raise PluginError(
+                            "resource_target_invalid",
+                            f"{name}/{resource.id} targets an unknown method",
+                        )
+                    if (
+                        target
+                        and target.methods[resource.data["method"]].audience
+                        != "business"
+                    ):
+                        raise PluginError(
+                            "resource_target_invalid",
+                            "Public MCP tools must target business methods",
+                        )
+        try:
+            self.order = tuple(TopologicalSorter(self.dependencies).static_order())
+        except CycleError as error:
+            raise PluginError(
+                "dependency_cycle", "Required service dependencies contain a cycle"
+            ) from error
+
+    def closure(self, name, *, optional=False, available=None):
+        result = set()
+
+        def visit(owner):
+            if owner in result:
+                return
+            result.add(owner)
+            for dependency in self.dependencies.get(owner, ()):
+                visit(dependency)
+            if optional:
+                for dependency, _ in self.bindings.get(owner, {}).values():
+                    if available is None or dependency in available:
+                        visit(dependency)
+
+        visit(name)
+        return result
+
+    def dependents(self, names):
+        result = set(names)
+        for name in self.order:
+            if self.dependencies[name] & result:
+                result.add(name)
+        return result
+
+    def resources(self, generations=None):
+        generations = generations or {}
+        return [
+            OwnedResource(
+                owner=name,
+                generation=generations.get(name, "candidate"),
+                resource=resource,
+                content=self.candidates[name].get("documents", {}).get(resource.id)
+                if resource.kind == "llms.document"
+                else None,
+            )
+            for name in sorted(self.definitions)
+            for resource in self.definitions[name].resources
+        ]
+
+    def descriptor_digest(self, kind):
+        return digest(
+            [
+                {
+                    "owner": resource.owner,
+                    "resource": resource.resource.model_dump(),
+                    "content": resource.content,
+                }
+                for resource in self.resources()
+                if resource.resource.kind == kind
+            ]
+        )
+
+    def affected(self, replacement, changed):
+        result = self.dependents(changed) | replacement.dependents(changed)
+        page_owners = {
+            resource.owner
+            for resource in self.resources() + replacement.resources()
+            if resource.resource.kind == "dashboard.page"
+        }
+        if result & page_owners:
+            result |= {
+                graph.providers["dashboard"]
+                for graph in (self, replacement)
+                if "dashboard" in graph.providers
+            }
+        if self.descriptor_digest("mcp.tool") != replacement.descriptor_digest(
+            "mcp.tool"
+        ):
+            result |= {
+                graph.providers["mcp"]
+                for graph in (self, replacement)
+                if "mcp" in graph.providers
+            }
+        return result