secondshift 0.1.0b12__py3-none-any.whl

secondshift/connections/execution.py

@@ -0,0 +1,262 @@
+"""What runs a workspace's jobs: one model key or one agent login."""
+
+from collections import Counter
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Any
+
+from django.conf import settings
+from django.contrib.auth.models import User
+from django.core.exceptions import ValidationError
+from django.utils import timezone
+
+from secondshift.config.constants import AgentBackend
+from secondshift.connections.agents import (
+    product_name,
+    sign_in_refused,
+    usable_agent_connection,
+)
+from secondshift.connections.dao import (
+    connected_logins,
+    has_models_or_logins,
+    login_run_counts,
+    usable_models,
+)
+from secondshift.connections.models import AgentConnection, Connection
+from secondshift.workspaces.models import Workspace
+
+# Choice keys name one model key or one login, for example "model:3" or "agent:7".
+MODEL_PREFIX = "model:"
+AGENT_PREFIX = "agent:"
+NOTHING_CHOSEN = "Choose a model API key or a subscription to run jobs."
+# A login's runs per day count over this rolling window.
+RUN_CAP_WINDOW = timedelta(hours=24)
+
+
+@dataclass(frozen=True)
+class ExecutionSelection:
+    key: str
+    label: str
+    backend: AgentBackend
+    connection: AgentConnection | None = None
+    model: Connection | None = None
+    problem: str = ""
+
+    @property
+    def ready(self) -> bool:
+        return not self.problem and (
+            self.connection is not None or self.model is not None
+        )
+
+
+def recent_login_runs(workspace_id: int) -> Counter[int]:
+    """Runs per agent login in the cap window. Only ready plans used a login."""
+    return login_run_counts(workspace_id, timezone.now() - RUN_CAP_WINDOW)
+
+
+def cli_enabled() -> bool:
+    return bool(settings.AGENT_IMAGE and settings.AGENT_BROKER_URL)
+
+
+def model_problem(model: Connection) -> str:
+    """Why runs cannot use this model key, or empty when they can."""
+    if model.status != Connection.Status.CONNECTED:
+        return f"The model provider {model.display_name} is disconnected. Reconnect it."
+    if not model.default_model.strip():
+        return f"The model provider {model.display_name} has no model selected."
+    if model.failed_last_check:
+        return f"The model provider {model.display_name} failed its last check."
+    return ""
+
+
+def workspace_model(workspace: Workspace) -> Connection | None:
+    """The chosen model provider, if runs can use it."""
+    model = workspace.default_model_connection
+    return None if model is None or model_problem(model) else model
+
+
+def model_selection(connection: Connection) -> ExecutionSelection:
+    problem = model_problem(connection)
+    return ExecutionSelection(
+        key=f"{MODEL_PREFIX}{connection.pk}",
+        label=f"Model provider · {connection.display_name}"
+        + ("" if problem else f" · {connection.default_model}"),
+        backend=AgentBackend.PYDANTIC,
+        model=None if problem else connection,
+        problem=problem,
+    )
+
+
+def subscription_problem(connection: AgentConnection, workspace: Workspace) -> str:
+    """Why runs cannot use this agent login, or empty when they can."""
+    if not cli_enabled():
+        return "Agent subscriptions are not set up on this server."
+    if not connection.connected:
+        return (
+            f"The agent login {connection.display_name} is disconnected. Reconnect it."
+        )
+    if sign_in_refused(connection):
+        return f"The agent login {connection.display_name} was refused at its last check. Reconnect it."
+    if not usable_agent_connection(connection, workspace.pk):
+        return f"The agent login {connection.display_name} belongs to someone who is no longer a workspace owner."
+    cap = connection.max_runs_per_day
+    if cap is not None and recent_login_runs(workspace.pk)[connection.pk] >= cap:
+        return (
+            f"The agent login {connection.display_name} reached its limit of "
+            f"{cap} runs in 24 hours. Raise its limit or wait."
+        )
+    return ""
+
+
+def subscription_selection(
+    connection: AgentConnection, workspace: Workspace
+) -> ExecutionSelection:
+    backend = AgentBackend(connection.backend)
+    product = product_name(backend)
+    return ExecutionSelection(
+        key=f"{AGENT_PREFIX}{connection.pk}",
+        label=f"{product} subscription · {connection.display_name}",
+        backend=backend,
+        connection=connection,
+        problem=subscription_problem(connection, workspace),
+    )
+
+
+def workspace_execution(workspace: Workspace) -> ExecutionSelection:
+    """What runs the workspace's jobs. It changes only when an owner changes it."""
+    if workspace.default_agent_connection_id:
+        return subscription_selection(workspace.default_agent_connection, workspace)
+    if workspace.default_model_connection_id:
+        return model_selection(workspace.default_model_connection)
+    return ExecutionSelection(
+        key="",
+        label="Nothing chosen",
+        backend=AgentBackend.PYDANTIC,
+        problem=NOTHING_CHOSEN,
+    )
+
+
+def execution_choices(workspace: Workspace, user: User) -> list[ExecutionSelection]:
+    """The workspace's model keys, then the user's own logins."""
+    models = usable_models(workspace)
+    logins = connected_logins(workspace, user)
+    return [
+        *(model_selection(model) for model in models),
+        *(subscription_selection(login, workspace) for login in logins),
+    ]
+
+
+def execution_configuration(workspace: Workspace, user: User) -> dict[str, Any]:
+    selected = workspace_execution(workspace)
+    choices = [
+        {
+            "key": choice.key,
+            "label": choice.label,
+            "disabled": not choice.ready,
+            "problem": choice.problem,
+        }
+        for choice in execution_choices(workspace, user)
+    ]
+    if selected.key and selected.key not in {choice["key"] for choice in choices}:
+        # Another owner's login or a disconnected provider. Shown, not selectable.
+        choices.append(
+            {
+                "key": selected.key,
+                "label": selected.label,
+                "disabled": True,
+                "problem": selected.problem,
+            }
+        )
+    return {
+        "enabled": cli_enabled(),
+        "choices": choices,
+        "selected": selected.key,
+        "label": selected.label,
+        "backend": selected.backend,
+        "ready": selected.ready,
+        "problem": selected.problem,
+    }
+
+
+def execution_status(workspace: Workspace) -> dict[str, Any]:
+    """What runs the jobs, why runs would fail, and where to fix it."""
+    selected = workspace_execution(workspace)
+    nothing_chosen = not selected.key
+    return {
+        "label": selected.label,
+        "backend": selected.backend,
+        "problem": selected.problem,
+        "chosen": not nothing_chosen,
+        "needs_setup": nothing_chosen and not has_models_or_logins(workspace.pk),
+        # The chosen model provider, so the page can open it ready to fix.
+        "fix_connection_id": workspace.default_model_connection_id
+        if selected.problem and not nothing_chosen and selected.backend.uses_model_api
+        else None,
+    }
+
+
+def choose_execution(
+    workspace: Workspace,
+    model: Connection | None = None,
+    login: AgentConnection | None = None,
+) -> None:
+    """Point the workspace at one model key or one login. None of both clears it."""
+    workspace.default_model_connection = model
+    workspace.default_agent_connection = login
+    workspace.save(
+        update_fields=[
+            "default_model_connection",
+            "default_agent_connection",
+            "updated_at",
+        ]
+    )
+
+
+def save_execution_preference(workspace: Workspace, key: str, user: User) -> None:
+    choice = next(
+        (
+            choice
+            for choice in execution_choices(workspace, user)
+            if choice.key == key and choice.ready
+        ),
+        None,
+    )
+    if choice is None:
+        raise ValidationError(
+            "Choose a working model provider or one of your own working logins."
+        )
+    choose_execution(workspace, model=choice.model, login=choice.connection)
+
+
+def use_when_nothing_runs(
+    workspace: Workspace,
+    model: Connection | None = None,
+    login: AgentConnection | None = None,
+) -> None:
+    """A new provider or login runs the jobs when nothing chosen can.
+
+    A broken newcomer only fills an empty choice, so it never hides a working
+    fix behind another problem. Settings shows the result.
+    """
+    current = workspace_execution(workspace)
+    if current.ready:
+        return
+    candidate = model_selection(model) if model else None
+    if current.key and candidate is not None and not candidate.ready:
+        return
+    choose_execution(workspace, model=model, login=login)
+
+
+def apply_model_default(connection: Connection, is_default: bool | None) -> None:
+    """The model provider form's default switch.
+
+    None means the form did not say, so the provider is used only when nothing
+    chosen can run jobs.
+    """
+    workspace = connection.workspace
+    if is_default:
+        choose_execution(workspace, model=connection)
+    elif is_default is None:
+        use_when_nothing_runs(workspace, model=connection)
+    elif workspace.default_model_connection_id == connection.pk:
+        choose_execution(workspace)

secondshift/connections/external.py

@@ -0,0 +1,258 @@
+"""External tools by connection kind: MCP servers and HTTP APIs.
+
+The planner, broker, and access review are the same for every kind. Each kind
+supplies only what differs: what a job may reach, what is frozen into a run
+plan, how a connection is checked against that plan, and how a call is made.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from asgiref.sync import async_to_sync
+
+from secondshift.connections.access import Access, AccessReason
+from secondshift.connections.errors import ExternalToolError
+from secondshift.connections.http_api.client import (
+    build_request,
+    send,
+    validate_api_connection,
+)
+from secondshift.connections.mcp.client import (
+    borrows_source,
+    mcp_request,
+    validate_mcp_connection,
+)
+from secondshift.connections.mcp.oauth import fresh_connection
+from secondshift.connections.mcp.providers import (
+    MCP_PROVIDERS,
+    mcp_provider,
+)
+from secondshift.connections.models import Connection
+from secondshift.connections.outbound import host_label
+from secondshift.connections.repository_ref import RepositoryRef
+
+
+@dataclass(frozen=True)
+class Authorization:
+    """A connection checked against the run's frozen plan, ready to call."""
+
+    connection: Connection
+    scope: str
+    # The frozen tool definition: description and inputSchema at least.
+    definition: dict[str, Any]
+    # Start of the model-facing tool name, such as "github" or "api".
+    name_prefix: str
+    scope_label: str
+    # The run's repository. Connections that borrow its source need it.
+    repository: RepositoryRef | None = None
+
+
+class ExternalKind(Protocol):
+    def access(self, connection: Connection, repository: RepositoryRef) -> Access: ...
+
+    def freeze(
+        self, connection: Connection, scope: str, tools: set[str]
+    ) -> dict[str, Any]: ...
+
+    def authorize(
+        self,
+        connection: Connection,
+        frozen: dict[str, Any],
+        repository: RepositoryRef,
+        tool: str,
+    ) -> Authorization: ...
+
+    def call(
+        self, authorization: Authorization, tool: str, arguments: dict[str, Any]
+    ) -> dict[str, Any]: ...
+
+
+def frozen_tools(connection: Connection, tools: set[str]) -> dict[str, Any]:
+    definitions = connection.tool_definitions
+    return {name: definitions.get(name) for name in sorted(tools)}
+
+
+def frozen_definition(
+    connection: Connection, frozen: dict[str, Any], tool: str, noun: str
+) -> dict[str, Any]:
+    definition = frozen.get("tools", {}).get(tool)
+    if not definition or definition != connection.tool_definitions.get(tool):
+        raise ExternalToolError(f"The {noun} definition changed. Start a new run.")
+    return definition
+
+
+class MCPKind:
+    def access(self, connection: Connection, repository: RepositoryRef) -> Access:
+        provider = MCP_PROVIDERS.get(connection.provider)
+        if provider is None:
+            return Access(
+                False,
+                None,
+                "This MCP provider is not supported.",
+                AccessReason.MCP_PROVIDER_UNSUPPORTED,
+            )
+        scope = provider.scope(connection.settings, repository)
+        if not scope:
+            return Access(
+                False,
+                None,
+                provider.missing_scope_message,
+                provider.missing_scope_reason,
+            )
+        if borrows_source(connection) and not provider.source_reachable(repository):
+            return Access(
+                False,
+                None,
+                provider.missing_source_message,
+                AccessReason.MCP_SOURCE_MISSING,
+            )
+        return Access(
+            True,
+            scope,
+            f"Allow these tools to {provider.access_verb} "
+            f"{provider.describe_scope(scope)}.",
+        )
+
+    def freeze(
+        self, connection: Connection, scope: str, tools: set[str]
+    ) -> dict[str, Any]:
+        """The approved scope and tool definitions. Never credentials."""
+        return {
+            "provider": connection.provider,
+            "scope": scope,
+            "tools": frozen_tools(connection, tools),
+        }
+
+    def authorize(
+        self,
+        connection: Connection,
+        frozen: dict[str, Any],
+        repository: RepositoryRef,
+        tool: str,
+    ) -> Authorization:
+        # Signed-in connections renew their token here, before the checks below.
+        fresh_connection(connection)
+        provider = validate_mcp_connection(connection)
+        if (
+            frozen.get("provider") != provider.key
+            or not frozen.get("scope")
+            or frozen["scope"] != provider.scope(connection.settings, repository)
+        ):
+            raise ExternalToolError(
+                f"The job {provider.scope_label} scope changed. Start a new run."
+            )
+        return Authorization(
+            connection=connection,
+            scope=frozen["scope"],
+            definition=frozen_definition(connection, frozen, tool, "MCP tool"),
+            name_prefix=provider.key,
+            scope_label=provider.scope_label,
+            repository=repository,
+        )
+
+    def call(
+        self, authorization: Authorization, tool: str, arguments: dict[str, Any]
+    ) -> dict[str, Any]:
+        connection = authorization.connection
+        provider = mcp_provider(connection.provider)
+        scoped = provider.scope_arguments(authorization.scope, tool, arguments)
+        token = ""
+        if borrows_source(connection):
+            if provider.source_token is None or authorization.repository is None:
+                raise ExternalToolError("This MCP connection has no repository.")
+            # Minted for this call and this repository only. Never stored.
+            token = provider.source_token(authorization.repository)
+        return async_to_sync(mcp_request)(connection, tool, scoped, token)
+
+
+class APIKind:
+    def access(self, connection: Connection, repository: RepositoryRef) -> Access:
+        del repository
+        base_url = connection.endpoint_url
+        if not base_url:
+            return Access(
+                False,
+                None,
+                "This API connection has no base URL.",
+                AccessReason.API_BASE_URL_UNKNOWN,
+            )
+        host = host_label(base_url)
+        return Access(
+            True,
+            host,
+            f"Allow these operations to use anything the credential can reach on {host}.",
+        )
+
+    def freeze(
+        self, connection: Connection, scope: str, tools: set[str]
+    ) -> dict[str, Any]:
+        return {
+            "base_url": connection.endpoint_url,
+            "scope": scope,
+            "tools": frozen_tools(connection, tools),
+        }
+
+    def authorize(
+        self,
+        connection: Connection,
+        frozen: dict[str, Any],
+        repository: RepositoryRef,
+        tool: str,
+    ) -> Authorization:
+        del repository
+        validate_api_connection(connection)
+        if not frozen.get("base_url") or frozen["base_url"] != connection.endpoint_url:
+            raise ExternalToolError("The API base URL changed. Start a new run.")
+        return Authorization(
+            connection=connection,
+            scope=frozen["scope"],
+            definition=frozen_definition(connection, frozen, tool, "API operation"),
+            name_prefix="api",
+            scope_label="API",
+        )
+
+    def call(
+        self, authorization: Authorization, tool: str, arguments: dict[str, Any]
+    ) -> dict[str, Any]:
+        del tool
+        request = build_request(
+            authorization.connection.endpoint_url, authorization.definition, arguments
+        )
+        return async_to_sync(send)(authorization.connection, request)
+
+
+EXTERNAL_KINDS: dict[str, ExternalKind] = {
+    Connection.Kind.MCP: MCPKind(),
+    Connection.Kind.API: APIKind(),
+}
+
+
+def external_kind(kind: str) -> ExternalKind:
+    try:
+        return EXTERNAL_KINDS[kind]
+    except KeyError:
+        raise ExternalToolError("This external tool is not supported.") from None
+
+
+def external_access(connection: Connection, repository: RepositoryRef) -> Access | None:
+    """None for connections that are not external tools, such as webhooks."""
+    adapter = EXTERNAL_KINDS.get(connection.kind)
+    return adapter.access(connection, repository) if adapter else None
+
+
+def changing_tools(connection: Connection, tools: list[str]) -> list[str]:
+    """Requested tools that may change data, for the access review.
+
+    Built-in MCP providers only offer allowlisted read tools. Custom servers
+    and HTTP APIs rely on the server's own read-only labels and HTTP methods.
+    """
+    if connection.kind == Connection.Kind.MCP:
+        provider = MCP_PROVIDERS.get(connection.provider)
+        if provider is None or not provider.owner_selects_tools:
+            return []
+    elif connection.kind != Connection.Kind.API:
+        return []
+    offered = connection.offered_tools
+    return [
+        name for name in tools if name in offered and not offered[name].get("readOnly")
+    ]

secondshift/connections/github.py

@@ -0,0 +1,123 @@
+"""GitHub source connections: how a workspace reaches its repositories."""
+
+from secondshift.connections.dao import save_github_source
+from secondshift.connections.models import Connection
+from secondshift.github import credentials
+from secondshift.github.app import configured
+from secondshift.github.errors import GitHubError
+from secondshift.github.installations import Installation
+from secondshift.github.tokens import inspect_token
+from secondshift.workspaces.models import Workspace
+
+
+def link_installations(
+    workspace: Workspace, installations: list[Installation]
+) -> list[Connection]:
+    """Add or reconnect one source connection per App installation."""
+    return [
+        save_github_source(
+            workspace,
+            installation.installation_id,
+            {
+                "kind": Connection.Kind.SOURCE,
+                "auth_strategy": Connection.AuthStrategy.MANAGED,
+                "display_name": f"GitHub · {installation.account}",
+                "status": Connection.Status.CONNECTED,
+            },
+        )
+        for installation in installations
+    ]
+
+
+# Keeps token connections apart from installations, whose IDs are numbers.
+TOKEN_ACCOUNT_PREFIX = "token:"
+
+
+def connect_token_source(
+    workspace: Workspace, token: str, replacing: Connection | None = None
+) -> Connection:
+    """Add a personal access token as a source, or replace the owner's last one.
+
+    GitHub checks the token first. A token for the same GitHub account
+    replaces the stored one, so its repositories keep working. When
+    replacing a given connection, the token must belong to its account.
+    """
+    owner = inspect_token(token.strip())
+    account_id = f"{TOKEN_ACCOUNT_PREFIX}{owner.login}"
+    if replacing is not None and replacing.external_account_id != account_id:
+        expected = replacing.external_account_id.removeprefix(TOKEN_ACCOUNT_PREFIX)
+        raise GitHubError(
+            f"This token belongs to {owner.login}. Use a token from {expected}."
+        )
+    return save_github_source(
+        workspace,
+        account_id,
+        {
+            "kind": Connection.Kind.SOURCE,
+            "auth_strategy": Connection.AuthStrategy.API_KEY,
+            "display_name": f"GitHub · {owner.login}",
+            "access_token": token.strip(),
+            "expires_at": owner.expires_at,
+            "status": Connection.Status.CONNECTED,
+        },
+    )
+
+
+def is_github_source(connection: Connection) -> bool:
+    return (
+        connection.provider == Connection.Provider.GITHUB
+        and connection.kind == Connection.Kind.SOURCE
+    )
+
+
+def shows_attribution(connection: Connection | None) -> bool:
+    """Whether what SecondShift publishes through this connection names it.
+
+    On by default for the App, whose bot already shows SecondShift's work.
+    Off by default for a personal token, which posts as a person who may
+    not want to say which tools they use.
+    """
+    if connection is None or not is_github_source(connection):
+        return True
+    if connection.attribution is not None:
+        return connection.attribution
+    return connection.auth_strategy != Connection.AuthStrategy.API_KEY
+
+
+def set_attribution(connection: Connection, attribution: bool) -> Connection:
+    connection.attribution = attribution
+    connection.save(update_fields=["attribution", "updated_at"])
+    return connection
+
+
+def usable_source(connection: Connection | None) -> bool:
+    if not (
+        connection
+        and connection.provider == Connection.Provider.GITHUB
+        and connection.kind == Connection.Kind.SOURCE
+        and connection.status == Connection.Status.CONNECTED
+    ):
+        return False
+    if connection.auth_strategy == Connection.AuthStrategy.MANAGED:
+        return True
+    return connection.auth_strategy == Connection.AuthStrategy.API_KEY and bool(
+        connection.access_token
+    )
+
+
+def can_check(connection: Connection | None) -> bool:
+    """App sources need the App on this server. Token sources need only themselves."""
+    return usable_source(connection) and (
+        connection.auth_strategy != Connection.AuthStrategy.MANAGED or configured()
+    )
+
+
+def connection_source(connection: Connection | None) -> credentials.Source:
+    """The credential behind a source connection. Never returned to a client."""
+    if not usable_source(connection):
+        raise GitHubError("The GitHub connection is disconnected.")
+    if connection.auth_strategy == Connection.AuthStrategy.MANAGED:
+        return credentials.AppInstallation(connection.external_account_id)
+    if connection.current_status == Connection.Status.EXPIRED:
+        raise GitHubError("The GitHub token expired. Enter a new one.")
+    return credentials.PersonalToken(connection.access_token)

secondshift/connections/http_api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API connections: operations from an OpenAPI spec, called by SecondShift."""