secondshift 0.1.0b12__py3-none-any.whl

secondshift/jobs/manifest.py

@@ -0,0 +1,364 @@
+import hashlib
+import json
+import re
+from pathlib import Path, PurePosixPath
+from typing import Annotated, ClassVar, Self
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import yaml
+from croniter import croniter
+from django.conf import settings
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    ValidationError,
+    field_validator,
+    model_validator,
+)
+from pydantic_core import ErrorDetails
+
+from secondshift.config.constants import (
+    COMMIT_SHA_PATTERN,
+    GITHUB_REPOSITORY_PATTERN,
+    MAX_RUN_ISSUES,
+    TriggerKind,
+)
+
+
+class CapabilityManifest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    binding: str = Field(pattern=r"^[a-z0-9]+(?:-[a-z0-9]+)*$", max_length=120)
+    tools: list[str] = Field(min_length=1)
+    required: bool = True
+
+    @field_validator("tools")
+    @classmethod
+    def validate_tools(cls, values: list[str]) -> list[str]:
+        if any(not value.strip() for value in values):
+            raise ValueError("tool names cannot be empty")
+        if len(values) != len(set(values)):
+            raise ValueError("tool names must be unique within a binding")
+        return values
+
+
+class RequirementsManifest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    mcps: list[CapabilityManifest] = Field(default_factory=list)
+    apis: list[CapabilityManifest] = Field(default_factory=list)
+
+
+class NotificationManifest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    binding: str = Field(pattern=r"^[a-z0-9]+(?:-[a-z0-9]+)*$", max_length=120)
+    required: bool = True
+
+
+# A dotted path to a field in a JSON body, such as "status" or "labels.team".
+FieldPath = Annotated[
+    str,
+    Field(pattern=r"^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$", max_length=200),
+]
+DURATION = re.compile(r"^(\d+)([mhd])$")
+DURATION_UNITS = {"m": 60, "h": 3600, "d": 86400}
+REPEAT_WINDOW_MAX_SECONDS = 7 * 86400
+
+
+def duration_seconds(value: str) -> int:
+    """Seconds in a duration such as "30m", "1h" or "2d"."""
+    match = DURATION.match(value)
+    if match is None:
+        raise ValueError("must be a number followed by m, h or d, such as 1h")
+    return int(match.group(1)) * DURATION_UNITS[match.group(2)]
+
+
+# Used when a job sets repeat_key without repeat_window.
+REPEAT_WINDOW_DEFAULT = "1h"
+
+
+class WebhookManifest(BaseModel):
+    """Which webhook requests start a run. Field names are the sender's."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Skip a request when every listed field has the listed value.
+    skip_when: dict[FieldPath, str | int | float | bool] = Field(default_factory=dict)
+    # Requests with the same value in this field are the same event.
+    repeat_key: FieldPath | None = None
+    # How long after its run a repeat is still skipped.
+    repeat_window: str | None = None
+
+    @field_validator("repeat_window")
+    @classmethod
+    def validate_repeat_window(cls, value: str | None) -> str | None:
+        if value is None:
+            return value
+        seconds = duration_seconds(value)
+        if not 0 < seconds <= REPEAT_WINDOW_MAX_SECONDS:
+            raise ValueError("must be between 1m and 7d")
+        return value
+
+    @property
+    def window(self) -> str:
+        """How long repeats are skipped, as written in the manifest."""
+        return self.repeat_window or REPEAT_WINDOW_DEFAULT
+
+    @model_validator(mode="after")
+    def validate_window_has_key(self) -> Self:
+        if self.repeat_window is not None and self.repeat_key is None:
+            raise ValueError("repeat_window needs a repeat_key")
+        return self
+
+
+class SkillSourceManifest(BaseModel):
+    """Another public GitHub repository that holds the job's skill.
+
+    The job's `skill` is then a path in that repository. Only the skill's
+    folder reaches the run, read-only at /skill.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    repository: str = Field(pattern=rf"^{GITHUB_REPOSITORY_PATTERN}$", max_length=200)
+    # A job pins a full commit SHA. A one-off task may name a branch or tag,
+    # or leave it out for the default branch.
+    ref: str | None = Field(default=None, min_length=1, max_length=200)
+
+    @property
+    def pinned(self) -> bool:
+        return self.ref is not None and bool(re.fullmatch(COMMIT_SHA_PATTERN, self.ref))
+
+
+IssueLabel = Annotated[
+    str, Field(min_length=1, max_length=50, pattern=r"^\S(?:.*\S)?$")
+]
+
+
+class OpenIssuesManifest(BaseModel):
+    """Where SecondShift opens the issues a job's agent proposes, and how many."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Added to every issue. The agent cannot choose labels.
+    labels: list[IssueLabel] = Field(default_factory=list, max_length=10)
+    max: int = Field(default=MAX_RUN_ISSUES, ge=1, le=MAX_RUN_ISSUES)
+
+    @field_validator("labels")
+    @classmethod
+    def distinct_labels(cls, value: list[str]) -> list[str]:
+        if len({label.casefold() for label in value}) != len(value):
+            raise ValueError("list each label once")
+        return value
+
+
+class JobManifest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    # A saved job runs only a skill someone reviewed, so its source is pinned.
+    pinned_sources: ClassVar[bool] = True
+
+    name: str = Field(min_length=1, max_length=200)
+    skill: str = Field(min_length=1, max_length=500)
+    # Where the skill comes from, when it is not in this repository.
+    skill_source: SkillSourceManifest | None = None
+    # Without a schedule, the job runs only when started with Run now.
+    schedule: str | None = Field(default=None, min_length=1, max_length=100)
+    timezone: str = "UTC"
+    # How many of the job's own earlier reports each run starts with.
+    history: int = Field(default=0, ge=0)
+    # How many sub-agents one run may start. They share the run's limits.
+    subagents: int = Field(default=0, ge=0)
+    requires: RequirementsManifest = Field(default_factory=RequirementsManifest)
+    notify: list[NotificationManifest] = Field(default_factory=list)
+    # Events that may start the job. An owner still turns each one on.
+    triggers: list[TriggerKind] = Field(default_factory=list)
+    webhook: WebhookManifest | None = None
+    # Open a draft pull request with the agent's changes. An owner still
+    # allows pull requests for the repository.
+    open_pull_request: bool = False
+    # Open the issues the agent proposes. true uses the defaults. An owner
+    # still allows issues for the repository.
+    open_issues: OpenIssuesManifest | None = None
+
+    @field_validator("open_issues", mode="before")
+    @classmethod
+    def open_issues_short_form(cls, value: object) -> object:
+        if value is True:
+            return {}
+        if value is False:
+            return None
+        return value
+
+    @field_validator("skill")
+    @classmethod
+    def validate_skill_path(cls, value: str) -> str:
+        path = PurePosixPath(value)
+        if path.is_absolute() or ".." in path.parts:
+            raise ValueError("skill must be a repository-relative path")
+        if path.name != "SKILL.md":
+            raise ValueError("skill must point to a SKILL.md file")
+        return value
+
+    @field_validator("triggers")
+    @classmethod
+    def validate_triggers(cls, values: list[TriggerKind]) -> list[TriggerKind]:
+        if len(values) != len(set(values)):
+            raise ValueError("triggers must be unique within a job")
+        return values
+
+    @field_validator("history")
+    @classmethod
+    def validate_history(cls, value: int) -> int:
+        if value > settings.JOB_HISTORY_MAX:
+            raise ValueError(
+                f"history cannot be above {settings.JOB_HISTORY_MAX} on this server"
+            )
+        return value
+
+    @field_validator("subagents")
+    @classmethod
+    def validate_subagents(cls, value: int) -> int:
+        if value > settings.RUN_SUBAGENTS_MAX:
+            raise ValueError(
+                f"subagents cannot be above {settings.RUN_SUBAGENTS_MAX} on this server"
+            )
+        return value
+
+    @field_validator("schedule")
+    @classmethod
+    def validate_schedule(cls, value: str | None) -> str | None:
+        if value is not None and not croniter.is_valid(value):
+            raise ValueError("schedule must be a valid five-field cron expression")
+        return value
+
+    @field_validator("timezone")
+    @classmethod
+    def validate_timezone(cls, value: str) -> str:
+        try:
+            ZoneInfo(value)
+        except ZoneInfoNotFoundError as error:
+            raise ValueError("timezone must be an IANA timezone") from error
+        return value
+
+    @model_validator(mode="after")
+    def validate_skill_source(self) -> Self:
+        if self.skill_source is None:
+            return self
+        if self.skill is None:
+            raise ValueError("skill_source needs a skill path in that repository")
+        if self.pinned_sources and not self.skill_source.pinned:
+            raise ValueError(
+                "skill_source.ref must be a full commit SHA, so a sync never "
+                "runs a skill nobody reviewed"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def validate_webhook_is_a_trigger(self) -> Self:
+        if self.webhook is not None and TriggerKind.WEBHOOK not in self.triggers:
+            raise ValueError("webhook settings need triggers: [webhook]")
+        return self
+
+    @model_validator(mode="after")
+    def validate_unique_bindings(self) -> Self:
+        bindings = [
+            item.binding
+            for item in [*self.requires.mcps, *self.requires.apis, *self.notify]
+        ]
+        if len(bindings) != len(set(bindings)):
+            raise ValueError("bindings must be unique within a job")
+        return self
+
+
+class TaskManifest(JobManifest):
+    """One-off work may supply instructions instead of a committed skill."""
+
+    pinned_sources: ClassVar[bool] = False
+
+    skill: str | None = Field(default=None, min_length=1, max_length=500)  # type: ignore[assignment]
+
+    @field_validator("skill")
+    @classmethod
+    def validate_skill_path(cls, value: str | None) -> str | None:
+        return JobManifest.validate_skill_path(value) if value is not None else None
+
+
+class RepositoryManifest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    version: int = 1
+    jobs: dict[str, JobManifest]
+
+    @field_validator("version")
+    @classmethod
+    def validate_version(cls, value: int) -> int:
+        if value != 1:
+            raise ValueError("only manifest version 1 is supported")
+        return value
+
+
+def load_manifest(path: Path) -> RepositoryManifest:
+    return parse_manifest(path.read_text())
+
+
+def parse_manifest(text: str) -> RepositoryManifest:
+    raw = yaml.safe_load(text)
+    if not isinstance(raw, dict):
+        raise ManifestError("The file must be a mapping.")
+    try:
+        return RepositoryManifest.model_validate(raw)
+    except ValidationError as error:
+        raise ManifestError(describe_errors(error)) from error
+
+
+class ManifestError(ValueError):
+    """A manifest problem, worded for the person who wrote the file."""
+
+
+def describe_errors(error: ValidationError) -> str:
+    unknown = [
+        field_path(item) for item in error.errors() if item["type"] == "extra_forbidden"
+    ]
+    problems = [
+        describe_error(item)
+        for item in error.errors()
+        if item["type"] != "extra_forbidden"
+    ]
+    if unknown:
+        label = "Unknown field" if len(unknown) == 1 else "Unknown fields"
+        problems.append(
+            f"{label}: {', '.join(unknown)}. Check the spelling, or update "
+            "SecondShift if the file was written for a newer version."
+        )
+    return " ".join(problems)
+
+
+def describe_error(item: ErrorDetails) -> str:
+    path = field_path(item)
+    if item["type"] == "missing":
+        return f"{path} is required."
+    message = item["msg"].removeprefix("Value error, ").rstrip(".")
+    message = message[:1].lower() + message[1:]
+    return f"{path}: {message}." if path else f"{message[:1].upper()}{message[1:]}."
+
+
+def field_path(item: ErrorDetails) -> str:
+    return ".".join(str(part) for part in item["loc"])
+
+
+def skill_key(job: JobManifest) -> str:
+    """Names the job's skill file among those a sync reads."""
+    if source := job.skill_source:
+        return f"{source.repository}@{source.ref}:{job.skill}"
+    return job.skill
+
+
+def manifest_hash(job: JobManifest) -> str:
+    data = job.model_dump()
+    if data["skill_source"] is None:
+        # Jobs written before skill sources keep the hash they had.
+        del data["skill_source"]
+    canonical = json.dumps(data, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode()).hexdigest()

secondshift/jobs/migrations/0001_initial.py

@@ -0,0 +1,87 @@
+# Generated by Django 6.0.9 on 2026-10-26 14:22
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('connections', '0001_initial'),
+        ('repositories', '0001_initial'),
+        ('workspaces', '0001_initial'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Job',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('max_turns', models.PositiveIntegerField(blank=True, null=True)),
+                ('max_tool_calls', models.PositiveIntegerField(blank=True, null=True)),
+                ('token_budget', models.PositiveBigIntegerField(blank=True, null=True)),
+                ('timeout_seconds', models.PositiveIntegerField(blank=True, null=True)),
+                ('key', models.SlugField(max_length=120)),
+                ('name', models.CharField(max_length=200)),
+                ('skill_path', models.CharField(max_length=500)),
+                ('cron', models.CharField(blank=True, default='', max_length=100)),
+                ('timezone', models.CharField(default='UTC', max_length=64)),
+                ('enabled', models.BooleanField(default=False)),
+                ('next_run_at', models.DateTimeField(blank=True, null=True)),
+                ('config_hash', models.CharField(max_length=64)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('repository', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='jobs', to='repositories.repository')),
+                ('workspace', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='jobs', to='workspaces.workspace')),
+            ],
+            options={
+                'ordering': ['repository__full_name', 'name'],
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='CapabilityRequest',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('binding', models.SlugField(max_length=120)),
+                ('kind', models.CharField(choices=[('mcp', 'MCP'), ('api', 'API'), ('notification', 'Notification')], max_length=24)),
+                ('requested_tools', models.JSONField(blank=True, default=list)),
+                ('required', models.BooleanField(default=True)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('job', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='capability_requests', to='jobs.job')),
+            ],
+            options={
+                'ordering': ['job', 'binding'],
+            },
+        ),
+        migrations.CreateModel(
+            name='JobGrant',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('status', models.CharField(choices=[('pending', 'Pending'), ('approved', 'Approved'), ('denied', 'Denied')], default='pending', max_length=16)),
+                ('allowed_tools', models.JSONField(blank=True, default=list)),
+                ('reviewed_at', models.DateTimeField(blank=True, null=True)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('capability_request', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, related_name='grant', to='jobs.capabilityrequest')),
+                ('connection', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='job_grants', to='connections.connection')),
+                ('reviewed_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='reviewed_job_grants', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'ordering': ['capability_request__job', 'capability_request__binding'],
+            },
+        ),
+        migrations.AddConstraint(
+            model_name='job',
+            constraint=models.UniqueConstraint(fields=('repository', 'key'), name='unique_repository_job_key'),
+        ),
+        migrations.AddConstraint(
+            model_name='capabilityrequest',
+            constraint=models.UniqueConstraint(fields=('job', 'binding'), name='unique_job_capability_binding'),
+        ),
+    ]

secondshift/jobs/migrations/0002_job_history.py

@@ -0,0 +1,18 @@
+# Generated by Django 6.0.9 on 2026-10-27 12:35
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('jobs', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='job',
+            name='history',
+            field=models.PositiveSmallIntegerField(default=0),
+        ),
+    ]

secondshift/jobs/migrations/0003_job_skill_text.py

@@ -0,0 +1,23 @@
+# Generated by Django 6.0.9 on 2026-10-29 09:13
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('jobs', '0002_job_history'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='job',
+            name='skill_text',
+            field=models.TextField(blank=True, default=''),
+        ),
+        migrations.AddField(
+            model_name='job',
+            name='skill_truncated',
+            field=models.BooleanField(default=False),
+        ),
+    ]

secondshift/jobs/migrations/0004_jobgrant_tool_rules.py

@@ -0,0 +1,18 @@
+# Generated by Django 6.0.9 on 2026-11-01 11:51
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('jobs', '0003_job_skill_text'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='jobgrant',
+            name='tool_rules',
+            field=models.JSONField(blank=True, default=dict),
+        ),
+    ]

secondshift/jobs/migrations/0005_job_triggers.py

@@ -0,0 +1,18 @@
+# Generated by Django 6.0.9 on 2026-11-01 17:20
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('jobs', '0004_jobgrant_tool_rules'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='job',
+            name='triggers',
+            field=models.JSONField(blank=True, default=list),
+        ),
+    ]

secondshift/jobs/migrations/0006_job_webhook.py

@@ -0,0 +1,18 @@
+# Generated by Django 6.0.9 on 2026-11-01 18:05
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('jobs', '0005_job_triggers'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='job',
+            name='webhook',
+            field=models.JSONField(blank=True, default=dict),
+        ),
+    ]

secondshift/jobs/migrations/0007_job_deliveries.py

@@ -0,0 +1,23 @@
+# Generated by Django 6.0.9 on 2026-11-04 11:50
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('jobs', '0006_job_webhook'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='job',
+            name='open_issues',
+            field=models.JSONField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name='job',
+            name='open_pull_request',
+            field=models.BooleanField(default=False),
+        ),
+    ]

secondshift/jobs/migrations/0008_job_removed_at.py

@@ -0,0 +1,18 @@
+# Generated by Django 6.0.9 on 2026-11-07 14:45
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('jobs', '0007_job_deliveries'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='job',
+            name='removed_at',
+            field=models.DateTimeField(blank=True, null=True),
+        ),
+    ]

secondshift/jobs/migrations/0009_job_subagents.py

@@ -0,0 +1,18 @@
+# Generated by Django 6.0.9 on 2026-11-07 16:01
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('jobs', '0008_job_removed_at'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='job',
+            name='subagents',
+            field=models.PositiveSmallIntegerField(default=0),
+        ),
+    ]

secondshift/jobs/migrations/0010_job_skill_source.py

@@ -0,0 +1,18 @@
+# Generated by Django 6.0.9 on 2026-11-11 19:20
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('jobs', '0009_job_subagents'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='job',
+            name='skill_source',
+            field=models.JSONField(blank=True, null=True),
+        ),
+    ]