minder-cli 0.2.0__py3-none-any.whl

minder/tools/workflow.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from minder.continuity import build_continuity_brief, build_instruction_envelope
+from minder.observability.metrics import (
+    record_continuity_gate,
+    record_continuity_packet,
+)
+from minder.store.interfaces import IOperationalStore
+from minder.store.repo_state import RepoStateStore
+
+
+class WorkflowTools:
+    def __init__(
+        self, store: IOperationalStore, repo_state_store: RepoStateStore
+    ) -> None:
+        self._store = store
+        self._repo_state = repo_state_store
+
+    async def minder_workflow_get(
+        self, *, repo_id: uuid.UUID, repo_path: str
+    ) -> dict[str, Any]:
+        repo = await self._require_repo(repo_id)
+        workflow = await self._require_workflow(repo.workflow_id)
+        state = await self._store.get_workflow_state_by_repo(repo_id)
+        relationships = (
+            dict(repo.relationships) if isinstance(repo.relationships, dict) else {}
+        )
+        await self._repo_state.write_relationships(repo_path, relationships)
+        if state is not None:
+            await self._repo_state.write_workflow_state(
+                repo_path,
+                {
+                    "current_step": state.current_step,
+                    "completed_steps": list(state.completed_steps),
+                    "blocked_by": list(state.blocked_by),
+                    "next_step": state.next_step,
+                },
+            )
+        return {
+            "workflow": {
+                "id": str(workflow.id),
+                "name": workflow.name,
+                "steps": list(workflow.steps),
+                "policies": dict(workflow.policies),
+            }
+        }
+
+    async def minder_workflow_step(
+        self, *, repo_id: uuid.UUID, repo_path: str
+    ) -> dict[str, Any]:
+        repo = await self._require_repo(repo_id)
+        workflow = await self._require_workflow(repo.workflow_id)
+        state = await self._require_workflow_state(repo_id)
+        payload = {
+            "current_step": state.current_step,
+            "completed_steps": list(state.completed_steps),
+            "blocked_by": list(state.blocked_by),
+            "next_step": state.next_step,
+            "instruction_envelope": build_instruction_envelope(
+                workflow=workflow,
+                workflow_state=state,
+            ),
+        }
+        await self._repo_state.write_workflow_state(repo_path, payload)
+        return payload
+
+    async def minder_workflow_update(
+        self,
+        *,
+        repo_id: uuid.UUID,
+        repo_path: str,
+        completed_step: str,
+        artifact_name: str | None = None,
+        artifact_content: str | None = None,
+    ) -> dict[str, Any]:
+        repo = await self._require_repo(repo_id)
+        workflow = await self._require_workflow(repo.workflow_id)
+        state = await self._require_workflow_state(repo_id)
+        step_names = [
+            step["name"]
+            for step in workflow.steps
+            if isinstance(step, dict) and "name" in step
+        ]
+        completed_steps = list(state.completed_steps)
+        if completed_step not in completed_steps:
+            completed_steps.append(completed_step)
+        next_step = self._next_step(completed_step, step_names)
+        artifacts = dict(state.artifacts)
+        if artifact_name and artifact_content is not None:
+            artifacts[artifact_name] = artifact_content
+            await self._repo_state.write_artifact(
+                repo_path, artifact_name, artifact_content
+            )
+        updated = await self._store.update_workflow_state(
+            state.id,
+            completed_steps=completed_steps,
+            current_step=next_step or completed_step,
+            next_step=self._next_step(next_step or completed_step, step_names),
+            artifacts=artifacts,
+        )
+        if updated is None:
+            raise ValueError(f"Workflow state not found for repo: {repo_id}")
+        await self._repo_state.write_workflow_state(
+            repo_path,
+            {
+                "current_step": updated.current_step,
+                "completed_steps": list(updated.completed_steps),
+                "blocked_by": list(updated.blocked_by),
+                "next_step": updated.next_step,
+            },
+        )
+        await self._repo_state.write_relationships(
+            repo_path,
+            dict(repo.relationships) if isinstance(repo.relationships, dict) else {},
+        )
+        return {
+            "current_step": updated.current_step,
+            "completed_steps": list(updated.completed_steps),
+            "next_step": updated.next_step,
+            "artifacts": dict(updated.artifacts),
+        }
+
+    async def minder_workflow_guard(
+        self,
+        *,
+        repo_id: uuid.UUID,
+        requested_step: str,
+        action: str | None = None,
+    ) -> dict[str, Any]:
+        repo = await self._require_repo(repo_id)
+        workflow = await self._require_workflow(repo.workflow_id)
+        state = await self._require_workflow_state(repo_id)
+        step_names = [
+            step["name"]
+            for step in workflow.steps
+            if isinstance(step, dict) and "name" in step
+        ]
+        expected_next = self._next_step(state.current_step, step_names)
+        allowed = requested_step == state.current_step or (
+            requested_step == expected_next
+            and state.current_step in list(state.completed_steps)
+            and not list(state.blocked_by)
+        )
+        violations: list[str] = []
+        if list(state.blocked_by):
+            violations.append("workflow_blocked")
+        if requested_step not in {state.current_step, expected_next}:
+            violations.append("step_skip_detected")
+        if action and requested_step != state.current_step:
+            violations.append("action_outside_current_step")
+        reason = (
+            None
+            if allowed
+            else f"Requested step '{requested_step}' is not allowed from '{state.current_step}'"
+        )
+        record_continuity_gate("passed" if allowed else "blocked")
+        record_continuity_packet("workflow_guard")
+        return {
+            "allowed": allowed,
+            "reason": reason,
+            "expected_next": expected_next,
+            "violations": violations,
+            "instruction_envelope": build_instruction_envelope(
+                workflow=workflow,
+                workflow_state=state,
+            ),
+            "continuity_brief": build_continuity_brief(
+                session=type(
+                    "WorkflowSessionView",
+                    (),
+                    {
+                        "id": getattr(state, "session_id", ""),
+                        "state": {},
+                        "project_context": {},
+                        "active_skills": {},
+                    },
+                )(),
+                workflow_state=state,
+                workflow=workflow,
+            ),
+        }
+
+    async def _require_repo(self, repo_id: uuid.UUID):  # noqa: ANN202
+        repo = await self._store.get_repository_by_id(repo_id)
+        if repo is None:
+            raise ValueError(f"Repository not found: {repo_id}")
+        return repo
+
+    async def _require_workflow(self, workflow_id: uuid.UUID | None):  # noqa: ANN202
+        if workflow_id is None:
+            raise ValueError("Repository has no workflow assigned")
+        workflow = await self._store.get_workflow_by_id(workflow_id)
+        if workflow is None:
+            raise ValueError(f"Workflow not found: {workflow_id}")
+        return workflow
+
+    async def _require_workflow_state(self, repo_id: uuid.UUID):  # noqa: ANN202
+        state = await self._store.get_workflow_state_by_repo(repo_id)
+        if state is None:
+            raise ValueError(f"Workflow state not found for repo: {repo_id}")
+        return state
+
+    @staticmethod
+    def _next_step(current_step: str, steps: list[str]) -> str | None:
+        try:
+            index = steps.index(current_step)
+        except ValueError:
+            return steps[0] if steps else None
+        next_index = index + 1
+        if next_index >= len(steps):
+            return None
+        return steps[next_index]

minder/transport/__init__.py

@@ -0,0 +1,4 @@
+from .sse import SSETransport
+from .stdio import StdioTransport
+
+__all__ = ["SSETransport", "StdioTransport"]

minder/transport/base.py

@@ -0,0 +1,286 @@
+import logging
+import inspect
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from mcp.server.fastmcp import FastMCP
+
+from minder.auth.middleware import AuthMiddleware
+from minder.auth.service import AuthError
+from minder.auth.rate_limiter import RateLimiter
+from minder.auth.principal import AdminUserPrincipal, ClientPrincipal, Principal
+from minder.auth.service import AuthService
+from minder.config import MinderConfig
+from minder.auth.context import get_current_principal
+from minder.store.interfaces import ICacheProvider, IOperationalStore
+from minder.tools.registry import ALWAYS_AVAILABLE_FOR_CLIENTS
+
+logger = logging.getLogger(__name__)
+
+ToolHandler = Callable[..., Any]
+
+
+@dataclass(slots=True)
+class RegisteredTool:
+    name: str
+    handler: ToolHandler
+    require_auth: bool
+    description: str | None = None
+
+
+class BaseTransport:
+    transport_name = "base"
+
+    def __init__(
+        self,
+        *,
+        config: MinderConfig,
+        auth_service: AuthService | None = None,
+        cache_provider: ICacheProvider,
+        store: IOperationalStore | None = None,
+    ) -> None:
+        self._config = config
+        self._store = store
+        self._middleware = AuthMiddleware(auth_service) if auth_service is not None else None
+        self._rate_limiter = RateLimiter(cache=cache_provider, config=config)
+        self._server = FastMCP(
+            name=config.server.name,
+            host=config.server.host,
+            port=config.server.port,
+        )
+        self._tools: dict[str, RegisteredTool] = {}
+
+    @property
+    def app(self) -> FastMCP:
+        return self._server
+
+    def register_tool(
+        self,
+        name: str,
+        handler: ToolHandler,
+        *,
+        require_auth: bool = True,
+        description: str | None = None,
+    ) -> None:
+        effective_description = description or inspect.getdoc(handler) or self._describe_tool(name)
+        self._tools[name] = RegisteredTool(
+            name=name,
+            handler=handler,
+            require_auth=require_auth,
+            description=effective_description,
+        )
+
+        # We need to wrap the handler to inject auth logic, but we must
+        # preserve the original signature so FastMCP can generate the tool schema correctly.
+        import functools
+
+        @functools.wraps(handler)
+        async def wrapped_tool(*args: Any, **kwargs: Any) -> Any:
+            # Authorization might come from minder_authorization in MCP CallTool params
+            authorization = kwargs.pop("minder_authorization", None)
+            client_key = kwargs.pop("minder_client_key", None)
+            
+            # Reconstruct arguments for call_tool
+            sig = inspect.signature(handler)
+            bound = sig.bind_partial(*args, **kwargs)
+            return await self.call_tool(
+                name,
+                arguments=bound.arguments,
+                authorization=authorization,
+                client_key=client_key,
+            )
+
+        # Modify the signature of wrapped_tool to remove 'user' parameter
+        # so FastMCP doesn't try to validate its presence in client requests.
+        orig_sig = inspect.signature(handler)
+        new_params = [
+            p for p in orig_sig.parameters.values() 
+            if p.name not in {"user", "principal"}
+        ]
+        # New parameters to inject (must be before VAR_KEYWORD if present)
+        injected = [
+            inspect.Parameter(
+                "minder_authorization",
+                kind=inspect.Parameter.KEYWORD_ONLY,
+                default=None,
+                annotation=str | None,
+            ),
+            inspect.Parameter(
+                "minder_client_key",
+                kind=inspect.Parameter.KEYWORD_ONLY,
+                default=None,
+                annotation=str | None,
+            ),
+        ]
+
+        final_params = []
+        var_kw = None
+        for p in new_params:
+            if p.kind == inspect.Parameter.VAR_KEYWORD:
+                var_kw = p
+            else:
+                final_params.append(p)
+
+        final_params.extend(injected)
+        if var_kw:
+            final_params.append(var_kw)
+
+        wrapped_tool.__signature__ = orig_sig.replace(parameters=final_params)  # type: ignore
+
+        self._server.add_tool(
+            wrapped_tool,
+            name=name,
+            description=effective_description,
+            structured_output=False,
+        )
+
+    def list_tools(self) -> list[str]:
+        return sorted(self._tools)
+
+    def _default_client_key(self) -> str | None:
+        return None
+
+    async def call_tool(
+        self,
+        name: str,
+        *,
+        arguments: dict[str, Any] | None = None,
+        authorization: str | None = None,
+        client_key: str | None = None,
+    ) -> Any:
+        if name not in self._tools:
+            raise KeyError(f"Unknown tool: {name}")
+
+        registered = self._tools[name]
+        kwargs = dict(arguments or {})
+        import time
+        start = time.perf_counter()
+        outcome = "error"
+        principal = None
+        try:
+            effective_client_key = client_key or self._default_client_key()
+            principal = await self._authenticate_if_required(registered, authorization, effective_client_key)
+            if principal is not None:
+                if (
+                    isinstance(principal, ClientPrincipal)
+                    and name not in ALWAYS_AVAILABLE_FOR_CLIENTS
+                    and name not in principal.scopes
+                ):
+                    outcome = "denied"
+                    raise AuthError(
+                        "AUTH_FORBIDDEN",
+                        f"Client is not allowed to call tool '{name}'",
+                    )
+                if self._rate_limiter.enabled():
+                    await self._rate_limiter.enforce(principal=principal, tool_name=name)
+                kwargs["principal"] = principal
+                if isinstance(principal, AdminUserPrincipal) and principal.user is not None:
+                    kwargs["user"] = principal.user
+            
+            outcome = "success"
+            return await _invoke(registered.handler, **kwargs)
+        except Exception as exc:
+            if isinstance(exc, AuthError):
+                outcome = "denied"
+            elif outcome == "success": # Should not happen if we caught an exception
+                outcome = "error"
+            raise
+        finally:
+            elapsed = time.perf_counter() - start
+            
+            client_id = "unknown"
+            actor_id = "unknown"
+            actor_type = "unknown"
+            if principal is not None:
+                client_id = getattr(principal, "client_slug") if hasattr(principal, "client_slug") else "unknown"
+                actor_id = str(principal.principal_id)
+                actor_type = principal.principal_type
+
+            # Record metrics (Prometheus - in-memory)
+            try:
+                from minder.observability.metrics import record_tool_call
+                record_tool_call(name, outcome, elapsed, client_id=client_id)
+            except Exception:
+                pass
+
+            # Record audit log (Persistent)
+            if self._store is not None:
+                try:
+                    await self._store.create_audit_log(
+                        actor_type=actor_type,
+                        actor_id=actor_id,
+                        event_type="tool_call",
+                        tool_name=name,
+                        resource_type="tool",
+                        resource_id=name,
+                        outcome=outcome,
+                        audit_metadata={
+                            "client_id": client_id,
+                            "latency_ms": round(elapsed * 1000, 2),
+                            "arguments": arguments,
+                        }
+                    )
+                except Exception:
+                    # Don't let audit logging fail the whole tool call
+                    pass
+
+    @staticmethod
+    def _describe_tool(name: str) -> str:
+        words = name.replace("minder_", "").replace("_", " ")
+        return f"Run the {words} tool in Minder."
+
+    async def _authenticate_if_required(
+        self,
+        registered: RegisteredTool,
+        authorization: str | None,
+        client_key: str | None,
+    ) -> Principal | None:
+        if not registered.require_auth:
+            return None
+        
+        # 1. Try context first (set by middleware or previous call in same task)
+        context_principal = get_current_principal()
+        if context_principal is not None:
+            logger.info(
+                "BaseTransport: found principal in context: %s",
+                context_principal.principal_type,
+            )
+            return context_principal
+
+        # 2. Fallback to explicit authorization header if provided
+        if self._middleware is None:
+            logger.error("BaseTransport: Transport requires auth but no AuthService was configured")
+            raise RuntimeError("Transport requires auth but no AuthService was configured")
+        
+        logger.debug(
+            "BaseTransport: no principal in context, checking auth header/client key",
+        )
+        principal = await self._middleware.authenticate_principal(
+            authorization,
+            client_key=client_key,
+        )
+        logger.info(
+            "BaseTransport: authenticated principal from request: %s",
+            principal.principal_type,
+        )
+        return principal
+
+
+async def _invoke(handler: ToolHandler, **kwargs: Any) -> Any:
+    signature = inspect.signature(handler)
+    accepts_var_kw = any(
+        parameter.kind == inspect.Parameter.VAR_KEYWORD
+        for parameter in signature.parameters.values()
+    )
+    if accepts_var_kw:
+        filtered_kwargs = kwargs
+    else:
+        filtered_kwargs = {
+            key: value
+            for key, value in kwargs.items()
+            if key in signature.parameters
+        }
+    result = handler(**filtered_kwargs)
+    if inspect.isawaitable(result):
+        return await result
+    return result