secondshift 0.1.0b12__py3-none-any.whl

secondshift/jobs/models.py

@@ -0,0 +1,199 @@
+from django.core.exceptions import ValidationError
+from django.db import models
+
+from secondshift.config.constants import MANIFEST_FILE
+from secondshift.connections.models import Connection
+from secondshift.jobs.manifest import OpenIssuesManifest, WebhookManifest
+from secondshift.repositories.models import Repository
+from secondshift.workspaces.models import RunLimitOverrides, Workspace
+
+# Why a job removed from the manifest cannot run or be resumed.
+JOB_REMOVED = f"This job is no longer in {MANIFEST_FILE}. Add it back to run it."
+
+
+class Job(RunLimitOverrides):
+    workspace = models.ForeignKey(
+        Workspace,
+        on_delete=models.CASCADE,
+        related_name="jobs",
+    )
+    repository = models.ForeignKey(
+        Repository,
+        on_delete=models.CASCADE,
+        related_name="jobs",
+    )
+    key = models.SlugField(max_length=120)
+    name = models.CharField(max_length=200)
+    skill_path = models.CharField(max_length=500)
+    # {"repository": "owner/name", "ref": <commit SHA>} when the skill is in
+    # another public GitHub repository. skill_path is then a path there.
+    skill_source = models.JSONField(null=True, blank=True)
+    # The skill file at the synced commit, for people to read before a run.
+    # Runs read the file from the commit, never from here.
+    skill_text = models.TextField(blank=True, default="")
+    skill_truncated = models.BooleanField(default=False)
+    # Empty for a job that runs only when started manually.
+    cron = models.CharField(max_length=100, blank=True, default="")
+    timezone = models.CharField(max_length=64, default="UTC")
+    # How many of its own earlier reports each run starts with.
+    history = models.PositiveSmallIntegerField(default=0)
+    # How many sub-agents one run may start.
+    subagents = models.PositiveSmallIntegerField(default=0)
+    # Trigger kinds the repository names, such as "webhook". See JobTrigger.
+    triggers = models.JSONField(default=list, blank=True)
+    # The repository's webhook settings: skip_when, repeat_key, repeat_window.
+    webhook = models.JSONField(default=dict, blank=True)
+    # The repository asks for a draft pull request with each run's changes.
+    open_pull_request = models.BooleanField(default=False)
+    # The repository asks to open the issues each run's agent proposes:
+    # {"labels": [...], "max": n}. None when it does not.
+    open_issues = models.JSONField(null=True, blank=True)
+    enabled = models.BooleanField(default=False)
+    next_run_at = models.DateTimeField(null=True, blank=True)
+    # Set when a sync no longer finds the job in the manifest. The job and its
+    # runs stay for history, but it cannot run until the manifest names it again.
+    removed_at = models.DateTimeField(null=True, blank=True)
+    config_hash = models.CharField(max_length=64)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta(RunLimitOverrides.Meta):
+        constraints = [
+            models.UniqueConstraint(
+                fields=["repository", "key"],
+                name="unique_repository_job_key",
+            )
+        ]
+        ordering = ["repository__full_name", "name"]
+
+    def __str__(self) -> str:
+        return f"{self.repository}: {self.name}"
+
+    @property
+    def webhook_settings(self) -> WebhookManifest | None:
+        return WebhookManifest.model_validate(self.webhook) if self.webhook else None
+
+    @property
+    def issue_settings(self) -> OpenIssuesManifest | None:
+        if not self.open_issues:
+            return None
+        return OpenIssuesManifest.model_validate(self.open_issues)
+
+    def capability_grant_status(self) -> str:
+        """Summarize the required grants already loaded for this job."""
+        requests = [
+            request for request in self.capability_requests.all() if request.required
+        ]
+        statuses = [
+            getattr(request, "grant", None).status
+            if hasattr(request, "grant")
+            else JobGrant.Status.PENDING
+            for request in requests
+        ]
+        if JobGrant.Status.DENIED in statuses:
+            return JobGrant.Status.DENIED
+        if statuses and all(status == JobGrant.Status.APPROVED for status in statuses):
+            return JobGrant.Status.APPROVED
+        return JobGrant.Status.PENDING if requests else "not_required"
+
+
+class CapabilityRequest(models.Model):
+    class Kind(models.TextChoices):
+        MCP = "mcp", "MCP"
+        API = "api", "API"
+        NOTIFICATION = "notification", "Notification"
+
+    job = models.ForeignKey(
+        Job,
+        on_delete=models.CASCADE,
+        related_name="capability_requests",
+    )
+    binding = models.SlugField(max_length=120)
+    kind = models.CharField(max_length=24, choices=Kind.choices)
+    requested_tools = models.JSONField(default=list, blank=True)
+    required = models.BooleanField(default=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(
+                fields=["job", "binding"],
+                name="unique_job_capability_binding",
+            )
+        ]
+        ordering = ["job", "binding"]
+
+    def __str__(self) -> str:
+        return f"{self.job}: {self.binding}"
+
+
+class JobGrant(models.Model):
+    class Status(models.TextChoices):
+        PENDING = "pending", "Pending"
+        APPROVED = "approved", "Approved"
+        DENIED = "denied", "Denied"
+
+    capability_request = models.OneToOneField(
+        CapabilityRequest,
+        on_delete=models.CASCADE,
+        related_name="grant",
+    )
+    connection = models.ForeignKey(
+        Connection,
+        on_delete=models.PROTECT,
+        related_name="job_grants",
+        null=True,
+        blank=True,
+    )
+    status = models.CharField(
+        max_length=16,
+        choices=Status.choices,
+        default=Status.PENDING,
+    )
+    allowed_tools = models.JSONField(default=list, blank=True)
+    # The owner's argument rules per approved tool. See jobs.tool_rules.
+    tool_rules = models.JSONField(default=dict, blank=True)
+    reviewed_by = models.ForeignKey(
+        "auth.User",
+        on_delete=models.PROTECT,
+        related_name="reviewed_job_grants",
+        null=True,
+        blank=True,
+    )
+    reviewed_at = models.DateTimeField(null=True, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ["capability_request__job", "capability_request__binding"]
+
+    def __str__(self) -> str:
+        return f"{self.capability_request}: {self.get_status_display()}"
+
+    def clean(self) -> None:
+        request = self.capability_request
+        connection = self.connection
+        if self.status == self.Status.APPROVED and connection is None:
+            raise ValidationError("Approved grants require a connection.")
+        if connection is None:
+            return
+        if request.job.workspace_id != connection.workspace_id:
+            raise ValidationError("Grant and connection must belong to one workspace.")
+        if request.kind != connection.kind:
+            raise ValidationError(
+                "Connection kind must match the requested capability."
+            )
+        if request.binding != connection.binding_key:
+            raise ValidationError(
+                "Connection binding must match the requested capability."
+            )
+        unknown_tools = set(self.allowed_tools) - set(request.requested_tools)
+        if unknown_tools:
+            raise ValidationError(
+                {"allowed_tools": "Allowed tools must be requested by the job."}
+            )
+        if set(self.tool_rules) - set(self.allowed_tools):
+            raise ValidationError(
+                {"tool_rules": "Rules can only apply to approved tools."}
+            )

secondshift/jobs/needs.py

@@ -0,0 +1,154 @@
+from dataclasses import dataclass, field
+from typing import Literal
+
+from secondshift.connections.access import Access
+from secondshift.connections.dao import connections_by_binding
+from secondshift.connections.external import EXTERNAL_KINDS, external_access
+from secondshift.connections.models import Connection
+from secondshift.jobs.dao import workspace_requests
+from secondshift.jobs.models import CapabilityRequest, JobGrant
+from secondshift.repositories.github import repository_ref
+from secondshift.repositories.models import Repository
+from secondshift.workspaces.models import Workspace
+
+NeedStatus = Literal["missing", "unavailable", "needs_approval", "ready"]
+STATUS_ORDER: dict[str, int] = {
+    "missing": 0,
+    "unavailable": 1,
+    "needs_approval": 2,
+    "ready": 3,
+}
+
+
+@dataclass
+class NeedJob:
+    job_id: int
+    job_name: str
+    repository: str
+    capability_id: int
+    required: bool
+    grant_status: str
+    access: Access | None = None
+
+
+@dataclass
+class CapabilityNeed:
+    binding: str
+    kind: str
+    required: bool
+    requested_tools: list[str]
+    status: NeedStatus
+    detail: str
+    connection: Connection | None
+    jobs: list[NeedJob] = field(default_factory=list)
+
+
+def connection_problem(
+    kind: str,
+    connection: Connection | None,
+    requested_tools: set[str],
+    repositories: list[Repository],
+) -> tuple[NeedStatus, str] | None:
+    """Why a binding cannot be used yet, before anyone approves it."""
+    if connection is None:
+        return "missing", "No workspace connection uses this binding yet."
+    if connection.kind != kind:
+        return (
+            "unavailable",
+            f"The {connection.binding_key} connection is a "
+            f"{connection.get_kind_display()} connection, not {kind}.",
+        )
+    if (status := connection.current_status) != Connection.Status.CONNECTED:
+        return (
+            "unavailable",
+            f"The connection is {Connection.Status(status).label.lower()}.",
+        )
+    if kind in EXTERNAL_KINDS:
+        for repository in repositories:
+            access = external_access(connection, repository_ref(repository))
+            if access and not access.ok:
+                return "unavailable", access.text
+    missing_tools = requested_tools - set(connection.available_tools)
+    if missing_tools:
+        return (
+            "unavailable",
+            "The connection does not provide: " + ", ".join(sorted(missing_tools)),
+        )
+    return None
+
+
+def need_status(
+    kind: str,
+    connection: Connection | None,
+    requests: list[CapabilityRequest],
+    requested_tools: set[str],
+) -> tuple[NeedStatus, str]:
+    problem = connection_problem(
+        kind,
+        connection,
+        requested_tools,
+        [request.job.repository for request in requests],
+    )
+    if problem:
+        return problem
+    unapproved = [
+        request
+        for request in requests
+        if getattr(request, "grant", None) is None
+        or request.grant.status == JobGrant.Status.PENDING
+    ]
+    if unapproved:
+        return "needs_approval", "Connected. Approve it for the jobs that use it."
+    return "ready", "Connected and reviewed for every job."
+
+
+def capability_needs(workspace: Workspace) -> list[CapabilityNeed]:
+    """Group every capability requested by active jobs by its logical binding."""
+    requests = workspace_requests(workspace)
+    connections = connections_by_binding(workspace.pk)
+    grouped: dict[tuple[str, str], list[CapabilityRequest]] = {}
+    for request in requests:
+        grouped.setdefault((request.binding, request.kind), []).append(request)
+
+    needs: list[CapabilityNeed] = []
+    for (binding, kind), items in grouped.items():
+        connection = connections.get(binding)
+        requested_tools = {tool for item in items for tool in item.requested_tools}
+        status, detail = need_status(kind, connection, items, requested_tools)
+        needs.append(
+            CapabilityNeed(
+                binding=binding,
+                kind=kind,
+                required=any(item.required for item in items),
+                requested_tools=sorted(requested_tools),
+                status=status,
+                detail=detail,
+                connection=connection,
+                jobs=[
+                    NeedJob(
+                        job_id=item.job_id,
+                        job_name=item.job.name,
+                        repository=item.job.repository.display_name,
+                        access=(
+                            external_access(
+                                connection, repository_ref(item.job.repository)
+                            )
+                            if connection and connection.kind == kind
+                            else None
+                        ),
+                        capability_id=item.pk,
+                        required=item.required,
+                        grant_status=(
+                            item.grant.status
+                            if getattr(item, "grant", None)
+                            else "unconfigured"
+                        ),
+                    )
+                    for item in items
+                ],
+            )
+        )
+    needs.sort(
+        key=lambda need: (STATUS_ORDER[need.status], not need.required, need.binding)
+    )
+    return needs

secondshift/jobs/plan.py

@@ -0,0 +1,176 @@
+"""The execution plan frozen into each run.
+
+The planner builds it once from server-owned policy. Runs, brokers and pages
+read it through these types. It never holds credentials.
+"""
+
+from enum import StrEnum
+from pathlib import PurePosixPath
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+from secondshift.config.constants import SANDBOX_SKILL_DIR, AgentBackend
+from secondshift.workspaces.limits import RunLimit
+
+
+class Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class Missing(StrEnum):
+    """Why a run does not have a binding, in words safe to show the model."""
+
+    NOT_CONNECTED = "not connected"
+    WAITING_FOR_APPROVAL = "waiting for approval"
+    DENIED = "denied"
+    UNAVAILABLE = "not available"
+
+
+class PlanReason(StrEnum):
+    """Why a capability is not authorized. Connections add AccessReason codes."""
+
+    NO_GRANT = "no_grant"
+    GRANT_PENDING = "grant_pending"
+    GRANT_DENIED = "grant_denied"
+    CONNECTION_MISSING = "connection_missing"
+    CONNECTION_EXPIRED = "connection_expired"
+    CONNECTION_REVOKED = "connection_revoked"
+    CONNECTION_WORKSPACE_MISMATCH = "connection_workspace_mismatch"
+    CONNECTION_KIND_MISMATCH = "connection_kind_mismatch"
+    CONNECTION_BINDING_MISMATCH = "connection_binding_mismatch"
+    TOOLS_NOT_GRANTED = "tools_not_granted"
+    TOOLS_UNAVAILABLE = "tools_unavailable"
+    TOOL_RULES_BROKEN = "tool_rules_broken"
+
+
+class ExecutionChoice(Frozen):
+    """The agent backend the workspace chose, and the login a CLI agent uses."""
+
+    backend: AgentBackend
+    label: str
+    ready: bool
+    problem: str
+    connection_id: int | None = None
+    credential_key: str | None = None
+    owner_id: int | None = None
+
+
+class PlanLimits(Frozen):
+    max_turns: int
+    max_tool_calls: int
+    max_tool_result_chars: int
+    token_budget: int
+    timeout_seconds: int
+
+    def value(self, limit: RunLimit) -> int:
+        return int(getattr(self, limit))
+
+
+class AgentPlan(Frozen):
+    limits: PlanLimits
+    # The only tool names the agent may call.
+    tools: tuple[str, ...]
+    subagents: int = 0
+
+
+class SkillSourcePlan(Frozen):
+    """A skill from another repository, pinned to the commit the run gets."""
+
+    repository: str
+    commit_sha: str
+
+
+class JobPlan(Frozen):
+    key: str
+    # A path in the run's repository, or in skill_source's when it is set.
+    skill_path: str
+    config_hash: str
+    skill_source: SkillSourcePlan | None = None
+
+    @property
+    def sandbox_skill_path(self) -> str:
+        """Where the agent reads the skill. Empty for written instructions."""
+        if self.skill_source is not None:
+            return f"{SANDBOX_SKILL_DIR}/{PurePosixPath(self.skill_path).name}"
+        return self.skill_path
+
+
+class RepositoryPlan(Frozen):
+    full_name: str
+    config_sha: str
+
+
+class RunnerPlan(Frozen):
+    image: str
+    network_policy: Literal["none"]
+    # Only runs that publish the agent's changes need them recorded.
+    collect_changes: bool
+
+
+class PullRequestPlan(Frozen):
+    """The draft pull request's base branch and CI choice."""
+
+    base: str
+    run_ci: bool
+
+
+class IssuesPlan(Frozen):
+    """How many issues the agent may propose, and the labels each gets."""
+
+    max: int
+    labels: tuple[str, ...]
+
+
+class ModelPlan(Frozen):
+    connection_id: int
+    connection_name: str
+    provider: str
+    family: str
+    default_model: str
+    allowed_models: tuple[str, ...]
+
+
+class CapabilityPlan(Frozen):
+    binding: str
+    kind: str
+    required: bool
+    requested_tools: tuple[str, ...]
+    connection_id: int | None
+    connection_name: str | None
+    effective_tools: tuple[str, ...]
+    authorized: bool
+    # PlanReason and AccessReason codes. Older runs may hold retired ones.
+    reasons: tuple[str, ...]
+    missing: Missing | None = None
+    # The approved scope and tool definitions of an external tool.
+    external: dict[str, Any] | None = None
+    # Copied in so a rule changed mid-run does not affect the run.
+    tool_rules: dict[str, dict[str, Any]] = {}
+
+
+class ExecutionPlan(Frozen):
+    execution: ExecutionChoice
+    ready: bool
+    agent: AgentPlan
+    job: JobPlan
+    repository: RepositoryPlan
+    runner: RunnerPlan
+    pull_request: PullRequestPlan | None
+    issues: IssuesPlan | None
+    model: ModelPlan | None
+    capabilities: tuple[CapabilityPlan, ...]
+
+    def limit(self, limit: RunLimit) -> int:
+        return self.agent.limits.value(limit)
+
+    def capability(self, kind: str, binding: str) -> CapabilityPlan:
+        return next(
+            item
+            for item in self.capabilities
+            if item.kind == kind and item.binding == binding
+        )
+
+    def stored(self) -> dict[str, Any]:
+        """The JSON saved on the run."""
+        return self.model_dump(mode="json")