secondshift 0.1.0b12__py3-none-any.whl

secondshift/jobs/sync.py

@@ -0,0 +1,252 @@
+"""Reconcile a repository's jobs, capability requests and grants with its manifest.
+
+Sync reads the existing rows once, creates new rows in bulk and saves only the
+rows that changed. Its query count stays the same however many jobs there are.
+"""
+
+from collections import defaultdict
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from django.db import models, transaction
+from django.utils import timezone
+
+from secondshift.config.constants import MAX_SKILL_PREVIEW_CHARS
+from secondshift.connections.dao import bound_connections
+from secondshift.jobs.automatic_grants import automatic_approval
+from secondshift.jobs.dao import (
+    create_capability_requests,
+    create_grants,
+    create_jobs,
+    delete_capability_requests,
+    repository_requests,
+    retire_missing_jobs,
+)
+from secondshift.jobs.manifest import (
+    CapabilityManifest,
+    JobManifest,
+    NotificationManifest,
+    RepositoryManifest,
+    manifest_hash,
+    skill_key,
+)
+from secondshift.jobs.models import CapabilityRequest, Job, JobGrant
+from secondshift.jobs.scheduling import next_occurrence
+from secondshift.jobs.tool_rules import kept_rules
+from secondshift.repositories.models import Repository
+
+
+@dataclass(frozen=True)
+class SyncedRequest:
+    request: CapabilityRequest
+    tools: list[str]
+    # False when this sync created the request.
+    existed: bool
+    # The manifest asks for more tools than before, or for another kind.
+    expanded: bool
+
+
+@transaction.atomic
+def sync_jobs(
+    repository: Repository,
+    manifest: RepositoryManifest,
+    skills: Mapping[str, str] | None = None,
+) -> list[Job]:
+    """`skills` maps each skill path to its text at the synced commit."""
+    jobs = sync_job_rows(repository, manifest, skills or {})
+    requests = sync_capability_requests(repository, jobs, manifest)
+    sync_grants(repository, requests)
+    retire_missing_jobs(repository, manifest.jobs.keys(), timezone.now())
+    repository.last_synced_at = timezone.now()
+    repository.save(update_fields=["last_synced_at", "updated_at"])
+    return jobs
+
+
+def assign(instance: models.Model, fields: Mapping[str, object]) -> list[str]:
+    """Set the fields that differ and return their names."""
+    changed = [
+        name for name, value in fields.items() if getattr(instance, name) != value
+    ]
+    for name in changed:
+        setattr(instance, name, fields[name])
+    return changed
+
+
+def save_changes(instance: models.Model, changed: list[str]) -> None:
+    if changed:
+        instance.save(update_fields=[*changed, "updated_at"])
+
+
+def job_fields(
+    repository: Repository, item: JobManifest, skill: str
+) -> dict[str, object]:
+    return {
+        "workspace_id": repository.workspace_id,
+        "name": item.name,
+        "skill_path": item.skill,
+        "skill_source": item.skill_source.model_dump() if item.skill_source else None,
+        "skill_text": skill[:MAX_SKILL_PREVIEW_CHARS],
+        "skill_truncated": len(skill) > MAX_SKILL_PREVIEW_CHARS,
+        "cron": item.schedule or "",
+        "timezone": item.timezone,
+        "history": item.history,
+        "subagents": item.subagents,
+        "triggers": [str(kind) for kind in item.triggers],
+        "webhook": item.webhook.model_dump(mode="json") if item.webhook else {},
+        "open_pull_request": item.open_pull_request,
+        "open_issues": item.open_issues.model_dump() if item.open_issues else None,
+        "config_hash": manifest_hash(item),
+        # A job named again comes back. Its schedule stays off until resumed.
+        "removed_at": None,
+    }
+
+
+def schedule(job: Job, changed: list[str]) -> list[str]:
+    """`changed` names the fields this sync changed on the job."""
+    if not job.cron:
+        # A job without a schedule is never on the scheduler.
+        return assign(job, {"next_run_at": None, "enabled": False})
+    if job.next_run_at is None or {"cron", "timezone"} & set(changed):
+        job.next_run_at = next_occurrence(job)
+        return ["next_run_at"]
+    return []
+
+
+def sync_job_rows(
+    repository: Repository, manifest: RepositoryManifest, skills: Mapping[str, str]
+) -> list[Job]:
+    existing = {job.key: job for job in repository.jobs.all()}
+    jobs: list[Job] = []
+    created: list[Job] = []
+    for key, item in manifest.jobs.items():
+        job = existing.get(key) or Job(key=key)
+        job.repository = repository
+        changed = assign(
+            job, job_fields(repository, item, skills.get(skill_key(item), ""))
+        )
+        changed += schedule(job, changed)
+        if job.pk is None:
+            created.append(job)
+        else:
+            save_changes(job, changed)
+        jobs.append(job)
+    create_jobs(created)
+    return jobs
+
+
+def requested_capabilities(
+    item: JobManifest,
+) -> list[tuple[str, CapabilityManifest | NotificationManifest]]:
+    return [
+        *(
+            (CapabilityRequest.Kind.MCP, capability)
+            for capability in item.requires.mcps
+        ),
+        *(
+            (CapabilityRequest.Kind.API, capability)
+            for capability in item.requires.apis
+        ),
+        *(
+            (CapabilityRequest.Kind.NOTIFICATION, notification)
+            for notification in item.notify
+        ),
+    ]
+
+
+def sync_capability_requests(
+    repository: Repository, jobs: list[Job], manifest: RepositoryManifest
+) -> list[SyncedRequest]:
+    existing: dict[int, dict[str, CapabilityRequest]] = defaultdict(dict)
+    for request in repository_requests(repository):
+        existing[request.job_id][request.binding] = request
+
+    synced: list[SyncedRequest] = []
+    created: list[CapabilityRequest] = []
+    stale: list[int] = []
+    for job, item in zip(jobs, manifest.jobs.values(), strict=True):
+        current = existing.pop(job.pk, {})
+        for kind, capability in requested_capabilities(item):
+            tools = list(getattr(capability, "tools", []))
+            fields = {
+                "kind": kind,
+                "requested_tools": tools,
+                "required": capability.required,
+            }
+            request = current.pop(capability.binding, None)
+            if request is None:
+                request = CapabilityRequest(
+                    job=job, binding=capability.binding, **fields
+                )
+                created.append(request)
+                synced.append(SyncedRequest(request, tools, False, False))
+                continue
+            expanded = (
+                not set(tools).issubset(request.requested_tools) or request.kind != kind
+            )
+            save_changes(request, assign(request, fields))
+            synced.append(SyncedRequest(request, tools, True, expanded))
+        # Bindings the manifest no longer asks for.
+        stale += [request.pk for request in current.values()]
+
+    create_capability_requests(created)
+    if stale:
+        delete_capability_requests(stale)
+    return synced
+
+
+def sync_grants(repository: Repository, requests: list[SyncedRequest]) -> None:
+    """Grant matching connections, and send changed requests back for review.
+
+    A waiting request is approved here when its connection does not require
+    approval and allows every tool it asks for.
+    """
+    connections = {
+        (connection.binding_key, connection.kind): connection
+        for connection in bound_connections(repository.workspace_id)
+    }
+    created: list[JobGrant] = []
+    for synced in requests:
+        request = synced.request
+        grant = getattr(request, "grant", None) if synced.existed else None
+        connection = connections.get((request.binding, request.kind))
+        new = grant is None
+        if grant is None:
+            if connection is None:
+                continue
+            grant = JobGrant(
+                capability_request=request,
+                connection=connection,
+                allowed_tools=sorted(synced.tools),
+            )
+        changed = assign(grant, review_fields(grant, synced)) if synced.existed else []
+        if (
+            grant.status == JobGrant.Status.PENDING
+            and connection is not None
+            and grant.connection_id in (None, connection.pk)
+            and (fields := automatic_approval(request, connection, repository))
+        ):
+            changed += assign(grant, fields)
+        if new:
+            created.append(grant)
+        else:
+            save_changes(grant, changed)
+    create_grants(created)
+
+
+def review_fields(grant: JobGrant, synced: SyncedRequest) -> dict[str, object]:
+    if synced.expanded:
+        # New tools need a fresh approval.
+        return {
+            "status": JobGrant.Status.PENDING,
+            "allowed_tools": sorted(synced.tools),
+            # Kept so the owner reviews them again with the new tools.
+            "tool_rules": kept_rules(grant.tool_rules, synced.tools),
+            "reviewed_by_id": None,
+            "reviewed_at": None,
+        }
+    # Tools the job stopped asking for are no longer allowed.
+    allowed = sorted(set(grant.allowed_tools) & set(synced.tools))
+    return {
+        "allowed_tools": allowed,
+        "tool_rules": kept_rules(grant.tool_rules, allowed),
+    }

secondshift/jobs/tool_policy.py

@@ -0,0 +1,82 @@
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from secondshift.jobs.plan import CapabilityPlan, ExecutionPlan
+
+LOCAL_TOOLS = (
+    "workspace.list_files",
+    "workspace.read_file",
+    "workspace.search_text",
+    "workspace.run_command",
+)
+EXTERNAL_KINDS = {"api", "mcp"}
+
+
+class ToolPolicyError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class AuthorizedTool:
+    name: str
+    kind: str
+    binding: str | None
+    provider_tool: str | None
+
+    @property
+    def is_local(self) -> bool:
+        return self.kind == "workspace"
+
+
+def external_tool_name(kind: str, binding: str, provider_tool: str) -> str:
+    """Namespace provider tools so bindings cannot collide in an agent turn."""
+    if kind not in EXTERNAL_KINDS:
+        raise ToolPolicyError(f"Unsupported external tool kind: {kind}")
+    if not binding or not provider_tool:
+        raise ToolPolicyError("External tools require a binding and tool name.")
+    return f"{kind}.{binding}.{provider_tool}"
+
+
+def plan_tools(
+    ready: bool, capabilities: Sequence[CapabilityPlan]
+) -> tuple[AuthorizedTool, ...]:
+    """Compile the only tool names that an agent may request for this run."""
+    tools = [
+        AuthorizedTool(name=name, kind="workspace", binding=None, provider_tool=None)
+        for name in LOCAL_TOOLS
+    ]
+    if not ready:
+        return tuple(tools)
+
+    for capability in capabilities:
+        if not capability.authorized or capability.kind not in EXTERNAL_KINDS:
+            continue
+        for provider_tool in capability.effective_tools:
+            tools.append(
+                AuthorizedTool(
+                    name=external_tool_name(
+                        capability.kind, capability.binding, provider_tool
+                    ),
+                    kind=capability.kind,
+                    binding=capability.binding,
+                    provider_tool=provider_tool,
+                )
+            )
+
+    by_name = {tool.name: tool for tool in tools}
+    if len(by_name) != len(tools):
+        raise ToolPolicyError("The execution plan produced duplicate tool names.")
+    return tuple(by_name[name] for name in sorted(by_name))
+
+
+def authorized_tools(plan: ExecutionPlan) -> tuple[AuthorizedTool, ...]:
+    return plan_tools(plan.ready, plan.capabilities)
+
+
+def resolve_tool(plan: ExecutionPlan, name: str) -> AuthorizedTool:
+    """Resolve a model-supplied name only through the frozen run policy."""
+    matches = {tool.name: tool for tool in authorized_tools(plan)}
+    try:
+        return matches[name]
+    except KeyError as error:
+        raise ToolPolicyError(f"Tool is not authorized for this run: {name}") from error

secondshift/jobs/tool_rules.py

@@ -0,0 +1,200 @@
+"""Owner rules that narrow the arguments of an approved tool.
+
+Rules are stored on a grant as `{tool: {property: rule}}`. Each rule applies to
+one top-level property of the tool's `inputSchema`:
+
+- fixed: the broker always sends this value. The model never sees the property.
+- allowed: the value must be one of these. The model must send it.
+- maximum: the value must not be larger. The model must send it.
+- forbidden: the model may not send the property at all.
+"""
+
+import copy
+from collections.abc import Mapping
+from enum import StrEnum
+from typing import Any
+
+from jsonschema import ValidationError, validate
+
+from secondshift.connections.errors import ExternalToolError
+
+ToolRules = dict[str, dict[str, dict[str, Any]]]
+
+
+class RuleType(StrEnum):
+    FIXED = "fixed"
+    ALLOWED = "allowed"
+    MAXIMUM = "maximum"
+    FORBIDDEN = "forbidden"
+
+
+NUMERIC_TYPES = {"integer", "number"}
+
+
+class ToolRuleError(ValueError):
+    """A rule the owner tried to save does not fit the tool."""
+
+
+class ToolRuleViolation(ExternalToolError):
+    """A call broke an owner rule. It never reaches the provider."""
+
+
+def property_types(schema: Mapping[str, Any]) -> set[str]:
+    declared = schema.get("type")
+    if isinstance(declared, str):
+        return {declared}
+    if isinstance(declared, list):
+        return {str(item) for item in declared}
+    return set()
+
+
+def fits(value: object, schema: Mapping[str, Any]) -> bool:
+    try:
+        validate(value, dict(schema))
+    except ValidationError:
+        return False
+    return True
+
+
+def value_problem(
+    rule: Mapping[str, Any], name: str, prop: Mapping[str, Any]
+) -> str | None:
+    kind = rule.get("type")
+    if kind == RuleType.FIXED:
+        if "value" not in rule or not fits(rule["value"], prop):
+            return f"The fixed value for `{name}` does not fit its type."
+        return None
+    values = rule.get("values")
+    if not isinstance(values, list) or not values:
+        return f"List at least one allowed value for `{name}`."
+    if not all(fits(value, prop) for value in values):
+        return f"An allowed value for `{name}` does not fit its type."
+    return None
+
+
+def maximum_problem(
+    rule: Mapping[str, Any], name: str, prop: Mapping[str, Any]
+) -> str | None:
+    value = rule.get("value")
+    if not property_types(prop) & NUMERIC_TYPES:
+        return f"`{name}` is not a number, so it cannot have a maximum."
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        return f"The maximum for `{name}` must be a number."
+    if not fits(value, prop):
+        return f"The maximum for `{name}` is outside what the tool accepts."
+    return None
+
+
+def rule_problem(
+    rule: Mapping[str, Any], name: str, schema: Mapping[str, Any]
+) -> str | None:
+    """Why a rule does not fit the tool's input schema. None when it fits."""
+    properties = schema.get("properties") or {}
+    if name not in properties:
+        return f"`{name}` is not an argument of this tool."
+    kind = rule.get("type")
+    if kind in (RuleType.FIXED, RuleType.ALLOWED):
+        return value_problem(rule, name, properties[name])
+    if kind == RuleType.MAXIMUM:
+        return maximum_problem(rule, name, properties[name])
+    if kind == RuleType.FORBIDDEN:
+        if name in (schema.get("required") or []):
+            return f"`{name}` is required by the tool, so it cannot be forbidden."
+        return None
+    return f"Unknown rule for `{name}`."
+
+
+def validate_rules(
+    rules: ToolRules, definitions: Mapping[str, Any], allowed_tools: list[str]
+) -> None:
+    """Raise ToolRuleError when any rule cannot apply to the approved tools."""
+    for tool, properties in rules.items():
+        if tool not in allowed_tools:
+            raise ToolRuleError(f"`{tool}` is not an approved tool.")
+        definition = definitions.get(tool) or {}
+        schema = definition.get("inputSchema") or {}
+        for name, rule in properties.items():
+            if problem := rule_problem(rule, name, schema):
+                raise ToolRuleError(f"{tool}: {problem}")
+
+
+def broken_rules(rules: ToolRules, definitions: Mapping[str, Any]) -> list[str]:
+    """Tools whose rules no longer fit, after the connection's schemas changed."""
+    broken = []
+    for tool, properties in sorted(rules.items()):
+        schema = (definitions.get(tool) or {}).get("inputSchema") or {}
+        if any(rule_problem(rule, name, schema) for name, rule in properties.items()):
+            broken.append(tool)
+    return broken
+
+
+def kept_rules(rules: ToolRules, tools: set[str] | list[str]) -> ToolRules:
+    """Only the rules for tools that are still approved or requested."""
+    return {
+        tool: rules[tool]
+        for tool in sorted(rules)
+        if tool in set(tools) and rules[tool]
+    }
+
+
+def apply_rules(
+    tool: str, rules: Mapping[str, Mapping[str, Any]], arguments: Mapping[str, Any]
+) -> dict[str, Any]:
+    """Set fixed values, then reject anything that breaks a rule.
+
+    The error names the property and the rule, never the value the model sent.
+    """
+    result = dict(arguments)
+    for name, rule in rules.items():
+        kind = rule["type"]
+        if kind == RuleType.FIXED:
+            result[name] = copy.deepcopy(rule["value"])
+        elif kind == RuleType.FORBIDDEN:
+            if name in result:
+                raise ToolRuleViolation(f"{tool}: `{name}` is not allowed.")
+        elif kind == RuleType.ALLOWED:
+            if name not in result or result[name] not in rule["values"]:
+                raise ToolRuleViolation(
+                    f"{tool}: `{name}` must be one of the approved values."
+                )
+        elif kind == RuleType.MAXIMUM:
+            value = result.get(name)
+            if (
+                isinstance(value, bool)
+                or not isinstance(value, int | float)
+                or value > rule["value"]
+            ):
+                raise ToolRuleViolation(
+                    f"{tool}: `{name}` must be at most {rule['value']}."
+                )
+    return result
+
+
+def narrow_schema(
+    schema: Mapping[str, Any], rules: Mapping[str, Mapping[str, Any]]
+) -> dict[str, Any]:
+    """The input schema the model sees, with the owner's rules applied."""
+    if not rules:
+        return dict(schema)
+    narrowed = copy.deepcopy(dict(schema))
+    properties = narrowed.setdefault("properties", {})
+    required = list(narrowed.get("required") or [])
+    for name, rule in rules.items():
+        kind = rule["type"]
+        if kind in (RuleType.FIXED, RuleType.FORBIDDEN):
+            properties.pop(name, None)
+            required = [item for item in required if item != name]
+            continue
+        prop = properties.get(name, {})
+        if kind == RuleType.ALLOWED:
+            properties[name] = {**prop, "enum": list(rule["values"])}
+        elif kind == RuleType.MAXIMUM:
+            ceiling = min(rule["value"], prop.get("maximum", rule["value"]))
+            properties[name] = {**prop, "maximum": ceiling}
+        if name not in required:
+            required.append(name)
+    if required:
+        narrowed["required"] = required
+    else:
+        narrowed.pop("required", None)
+    return narrowed

secondshift/mcp_server/__init__.py

@@ -0,0 +1,6 @@
+"""The MCP server: tools for coding agents and other integrations.
+
+Clients sign in with an API token (see secondshift.workspaces.tokens). Each
+tool is a thin adapter over the same service as the matching HTTP view. See
+docs/mcp.md.
+"""

secondshift/mcp_server/api.py

@@ -0,0 +1,79 @@
+"""The /mcp endpoint: token auth, a rate limit, protocol dispatch and audit."""
+
+import logging
+
+from django.conf import settings
+from django.http import HttpRequest, HttpResponse
+from ninja.throttling import UserRateThrottle
+from thin_mcp import (
+    JsonRpcErrorCode,
+    McpHttpResult,
+    McpMethodName,
+    McpRequest,
+    McpRequestHeaders,
+)
+from thin_mcp.django_ninja import McpAPI, render_mcp_result
+
+from secondshift.mcp_server.audit import record_call
+from secondshift.mcp_server.core import server
+from secondshift.mcp_server.models import ToolCall
+from secondshift.mcp_server.tools_registry import McpCall
+from secondshift.workspaces.models import ApiToken
+from secondshift.workspaces.tokens import ApiTokenAuth
+
+logger = logging.getLogger(__name__)
+
+# Counts requests per person, across all their tokens. It runs after token
+# auth, which signs the request in as the token's creator, and keeps its
+# counts in the shared cache.
+throttle = UserRateThrottle(f"{settings.MCP_RATE_LIMIT}/m")
+
+api = McpAPI(
+    title="SecondShift MCP",
+    urls_namespace="mcp",
+    auth=ApiTokenAuth(),
+    throttle=throttle,
+    docs_url=None,
+    openapi_url=None,
+)
+
+
+def tool_name(payload: McpRequest) -> str:
+    name = payload.params.get("name")
+    return name if isinstance(name, str) else ""
+
+
+def dispatch(request: HttpRequest, payload: McpRequest) -> McpHttpResult:
+    try:
+        return server.dispatch_request(
+            user=request.user, request=payload, resources=(McpCall(request),)
+        )
+    except Exception:
+        logger.exception("Unhandled MCP request error")
+        if payload.is_notification:
+            return McpHttpResult.accepted()
+        return McpHttpResult.error(
+            payload.id, JsonRpcErrorCode.INTERNAL_ERROR, "Internal error.", status=500
+        )
+
+
+def outcome(result: McpHttpResult) -> ToolCall.Outcome:
+    body = result.body.model_dump(by_alias=True) if result.body else {}
+    tool_result = body.get("result") or {}
+    if "error" in body or tool_result.get("isError"):
+        return ToolCall.Outcome.ERROR
+    return ToolCall.Outcome.OK
+
+
+@api.post("")
+def mcp_endpoint(request: HttpRequest, payload: McpRequest) -> HttpResponse:
+    token: ApiToken = request.auth
+    headers = McpRequestHeaders.from_mapping(request.headers)
+    invalid = server.validate_http_request(payload, headers)
+    if invalid is not None:
+        return render_mcp_result(invalid)
+    if payload.method != McpMethodName.TOOLS_CALL:
+        return render_mcp_result(dispatch(request, payload))
+    result = dispatch(request, payload)
+    record_call(token, tool_name(payload), outcome(result))
+    return render_mcp_result(result)

secondshift/mcp_server/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class McpServerConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "secondshift.mcp_server"
+    label = "mcp_server"

secondshift/mcp_server/audit.py

@@ -0,0 +1,22 @@
+"""Audit records of MCP tool calls, kept as long as runs."""
+
+from datetime import timedelta
+
+from django.conf import settings
+from django.utils import timezone
+
+from secondshift.mcp_server.dao import create_tool_call, delete_tool_calls_before
+from secondshift.mcp_server.models import TOOL_NAME_MAX, ToolCall
+from secondshift.workspaces.models import ApiToken
+
+
+def record_call(token: ApiToken, tool: str, outcome: ToolCall.Outcome) -> None:
+    create_tool_call(token, tool[:TOOL_NAME_MAX], outcome)
+
+
+def prune_tool_calls(days: int | None = None) -> int:
+    """Delete tool calls older than the run retention window."""
+    days = settings.RUN_RETENTION_DAYS if days is None else days
+    if days <= 0:
+        return 0
+    return delete_tool_calls_before(timezone.now() - timedelta(days=days))

secondshift/mcp_server/core.py

@@ -0,0 +1,12 @@
+from importlib.metadata import version
+
+from thin_mcp import McpServer
+
+from secondshift.mcp_server.tools import registry
+
+server = McpServer(
+    name="secondshift",
+    version=version("secondshift"),
+    protocol_versions=("2025-03-26", "2025-06-18", "2025-11-25", "2026-07-28"),
+    tools=registry,
+)

secondshift/mcp_server/dao.py

@@ -0,0 +1,23 @@
+"""Queries and writes on MCP tool call records."""
+
+from datetime import datetime
+
+from secondshift.mcp_server.models import ToolCall
+from secondshift.workspaces.models import ApiToken
+
+
+def create_tool_call(token: ApiToken, tool: str, outcome: ToolCall.Outcome) -> ToolCall:
+    """Record one tool call made with this token."""
+    return ToolCall.objects.create(
+        workspace_id=token.workspace_id,
+        token=token,
+        user_id=token.created_by_id,
+        tool=tool,
+        outcome=outcome,
+    )
+
+
+def delete_tool_calls_before(cutoff: datetime) -> int:
+    """Delete tool calls made before the cutoff. Returns how many."""
+    deleted, _ = ToolCall.objects.filter(created_at__lt=cutoff).delete()
+    return deleted