codee-agent 0.1.0__py3-none-any.whl

codee_tasks_abstract/provider.py

@@ -0,0 +1,58 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+from codee_main_context.context import Settings
+
+
+@dataclass
+class Task:
+    """Provider-agnostic representation of a task to be worked on.
+
+    Models the fields the executor reads out of a JIRA issue, so any provider
+    (JIRA, Azure DevOps, ...) can be reduced to the same shape.
+    """
+
+    key: str
+    summary: str
+    status: str
+    issue_type: str
+    priority: str
+    labels: list[str] = field(default_factory=list)
+    parent: "Task | None" = None
+
+    @property
+    def is_parent_codee_story(self) -> bool:
+        """Whether this task hangs under a story Codee owns.
+
+        What marks a story as Codee-owned is provider-specific — a label in
+        JIRA, a work item type in Azure DevOps — so each provider answers this
+        for its own tasks. The executor only asks the question. A provider that
+        has no notion of Codee stories inherits "no parent story".
+        """
+        return False
+
+
+class AbstractTasksProvider(ABC):
+    """Base class every tasks provider (e.g. JIRA) inherits from.
+
+    A provider is constructed from the app ``Settings`` and initializes itself
+    from its own stored credentials, so the executor never has to know which
+    provider it's talking to or what configuration that provider needs.
+    """
+
+    def __init__(self, settings: Settings):
+        """Initialize the provider from the stored settings."""
+
+    @abstractmethod
+    def is_configured(self) -> bool:
+        """Whether the provider has enough configuration to fetch tasks."""
+        ...
+
+    @abstractmethod
+    def get_tasks(self, statuses: list[str]) -> list[Task]:
+        """Return agent-owned tasks in the requested statuses, highest priority first."""
+        ...
+
+    def describe(self) -> str:
+        """Human-readable one-liner about this provider's config, for logs."""
+        return type(self).__name__

codee_tasks_azure_devops/oauth.py

@@ -0,0 +1,346 @@
+"""Entra ID authorization-code flow for Azure DevOps, with automatic refresh.
+
+Scope note: Azure DevOps publishes exactly one delegated permission through an
+Entra ID app registration — ``user_impersonation``. There is no read-only
+variant to ask for (the granular ``vso.work`` family only exists in the legacy,
+now-deprecated Azure DevOps OAuth app model). Read-only access is therefore
+enforced on our side: this package only ever issues reads — GETs and WIQL
+queries — and never a create, update, or transition. Narrow it further on the
+Azure DevOps side by authorizing with an account that has Readers access.
+
+The flow is confidential-client: the code is exchanged for tokens on the
+backend using the app's client secret, so the secret never reaches the browser.
+PKCE is layered on top even though a secret is used, which keeps an intercepted
+code useless on its own.
+"""
+import base64
+import hashlib
+import secrets
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from urllib.parse import urlencode
+
+import requests
+from codee_database import oauth_tokens
+from codee_main_context.context import CodeeMainContext, Settings, TasksProvider
+
+# Fixed Entra ID application ID of the Azure DevOps resource. Same value in
+# every tenant; it is what makes a token usable against dev.azure.com.
+AZURE_DEVOPS_RESOURCE_ID = "499b84ac-1321-427f-aa17-267ca6975798"
+SCOPE = f"{AZURE_DEVOPS_RESOURCE_ID}/user_impersonation offline_access"
+
+PROVIDER = TasksProvider.AZURE_DEVOPS.value
+
+# Path the admin UI serves the callback on. Registered verbatim (behind the
+# admin host) as a redirect URI on the Entra app; Entra matches it exactly.
+CALLBACK_PATH = "/api/oauth/azure-devops/callback"
+
+# Refresh this far ahead of the stated expiry, so a token can't lapse midway
+# through a request that already passed the check.
+EXPIRY_MARGIN = timedelta(seconds=120)
+
+# Used when no directory is configured: covers any work/school account, which
+# is the only kind Azure DevOps organizations are backed by.
+DEFAULT_TENANT = "organizations"
+
+_TIMEOUT = 30
+
+
+class AzureDevOpsAuthError(RuntimeError):
+    """Authorization failed.
+
+    ``terminal`` separates "this refresh token is dead, the user must consent
+    again" from "this attempt failed, the next one may not" — an unreachable
+    Entra, a 5xx, a throttle, or a client secret that needs correcting in
+    Settings. Only a terminal failure justifies discarding a refresh token that
+    might still be worth 90 days of unattended operation.
+    """
+
+    def __init__(self, message: str, terminal: bool = False):
+        super().__init__(message)
+        self.terminal = terminal
+
+
+@dataclass(frozen=True)
+class OAuthConfig:
+    """The Entra app registration, as captured in settings.json."""
+
+    organization_url: str = ""
+    project: str = ""
+    tenant_id: str = ""
+    client_id: str = ""
+    client_secret: str = ""
+
+    @classmethod
+    def from_settings(cls, settings: Settings) -> "OAuthConfig":
+        creds = settings.credentials.get(PROVIDER, {})
+        return cls(
+            organization_url=(creds.get("organization_url") or "").strip().rstrip("/"),
+            project=(creds.get("project") or "").strip(),
+            tenant_id=(creds.get("tenant_id") or "").strip(),
+            client_id=(creds.get("client_id") or "").strip(),
+            client_secret=(creds.get("client_secret") or "").strip(),
+        )
+
+    def is_complete(self) -> bool:
+        """Whether we have everything needed to run the flow and query tasks."""
+        return bool(self.organization_url and self.project
+                    and self.client_id and self.client_secret)
+
+    @property
+    def tenant(self) -> str:
+        return self.tenant_id or DEFAULT_TENANT
+
+    @property
+    def authorize_endpoint(self) -> str:
+        return f"https://login.microsoftonline.com/{self.tenant}/oauth2/v2.0/authorize"
+
+    @property
+    def token_endpoint(self) -> str:
+        return f"https://login.microsoftonline.com/{self.tenant}/oauth2/v2.0/token"
+
+
+def new_state() -> str:
+    """Opaque value tying the callback back to the request that started it."""
+    return secrets.token_urlsafe(32)
+
+
+def new_code_verifier() -> str:
+    return secrets.token_urlsafe(64)
+
+
+def code_challenge_for(code_verifier: str) -> str:
+    digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
+    return base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
+
+
+def build_authorization_url(
+    config: OAuthConfig,
+    redirect_uri: str,
+    state: str,
+    code_verifier: str,
+) -> str:
+    """The Entra URL to send the browser to for consent."""
+    query = urlencode({
+        "client_id": config.client_id,
+        "response_type": "code",
+        "redirect_uri": redirect_uri,
+        "response_mode": "query",
+        "scope": SCOPE,
+        "state": state,
+        "code_challenge": code_challenge_for(code_verifier),
+        "code_challenge_method": "S256",
+        # Force account selection: the admin may well be signed into a personal
+        # account that has no access to the organization.
+        "prompt": "select_account",
+    })
+    return f"{config.authorize_endpoint}?{query}"
+
+
+def exchange_code(
+    config: OAuthConfig,
+    redirect_uri: str,
+    code: str,
+    code_verifier: str,
+) -> dict:
+    """Trade an authorization code for access + refresh tokens."""
+    return _post_token(config, {
+        "client_id": config.client_id,
+        "client_secret": config.client_secret,
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": redirect_uri,
+        "code_verifier": code_verifier,
+        "scope": SCOPE,
+    })
+
+
+def refresh_access_token(config: OAuthConfig, refresh_token: str) -> dict:
+    """Trade a refresh token for a fresh access token (and usually a new refresh token)."""
+    return _post_token(config, {
+        "client_id": config.client_id,
+        "client_secret": config.client_secret,
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "scope": SCOPE,
+    })
+
+
+def _post_token(config: OAuthConfig, data: dict) -> dict:
+    """POST to the token endpoint and normalize the response.
+
+    Returns ``{access_token, refresh_token, expires_at, scope}`` with
+    ``expires_at`` as a UTC ISO timestamp, so callers never have to reason
+    about the relative ``expires_in`` they were handed.
+    """
+    try:
+        response = requests.post(
+            config.token_endpoint,
+            data=data,
+            headers={"Accept": "application/json"},
+            timeout=_TIMEOUT,
+        )
+    except requests.RequestException as exc:
+        raise AzureDevOpsAuthError(f"Could not reach Entra ID: {exc}") from exc
+
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = {}
+
+    if response.status_code >= 400 or "access_token" not in payload:
+        raise AzureDevOpsAuthError(
+            _describe_token_error(response, payload),
+            terminal=_is_terminal_token_error(response, payload))
+
+    expires_in = payload.get("expires_in")
+    try:
+        seconds = int(expires_in)
+    except (TypeError, ValueError):
+        seconds = 3600  # ponytail: no expiry given -> assume the documented default
+    return {
+        "access_token": payload["access_token"],
+        "refresh_token": payload.get("refresh_token"),
+        "expires_at": (datetime.now(timezone.utc)
+                       + timedelta(seconds=seconds)).isoformat(),
+        "scope": payload.get("scope", ""),
+    }
+
+
+def _is_terminal_token_error(response, payload: dict) -> bool:
+    """Whether the stored refresh token can never be redeemed again.
+
+    Only ``invalid_grant`` says that — the grant itself is revoked, expired, or
+    consent was withdrawn. Everything else is about this attempt: 5xx and 429
+    are Entra having a moment, and ``invalid_client`` means the secret in
+    Settings needs fixing, which leaves the refresh token perfectly good.
+    """
+    if response.status_code >= 500 or response.status_code == 429:
+        return False
+    return payload.get("error") == "invalid_grant"
+
+
+def _describe_token_error(response, payload: dict) -> str:
+    """Entra's error_description is multi-line with correlation IDs; keep line one."""
+    description = str(payload.get("error_description") or "").strip()
+    if description:
+        return description.splitlines()[0]
+    error = payload.get("error")
+    return str(error) if error else f"Entra ID returned HTTP {response.status_code}"
+
+
+def fetch_account(access_token: str) -> str:
+    """Best-effort display name of the account that authorized, for the UI.
+
+    A failure here says nothing about the token's usefulness for work items, so
+    it degrades to an empty label instead of failing the connection.
+    """
+    try:
+        response = requests.get(
+            "https://app.vssps.visualstudio.com/_apis/profile/profiles/me",
+            params={"api-version": "7.1"},
+            headers={"Authorization": f"Bearer {access_token}",
+                     "Accept": "application/json"},
+            timeout=_TIMEOUT,
+        )
+        response.raise_for_status()
+        profile = response.json()
+    except (requests.RequestException, ValueError):
+        return ""
+    return str(profile.get("emailAddress") or profile.get("displayName") or "")
+
+
+def is_expired(expires_at: str | None, now: datetime | None = None) -> bool:
+    """Whether a stored expiry has passed, or is close enough to count as passed."""
+    if not expires_at:
+        return True  # ponytail: unknown expiry -> refresh rather than send a dud token
+    try:
+        deadline = datetime.fromisoformat(expires_at)
+    except (TypeError, ValueError):
+        return True
+    if deadline.tzinfo is None:
+        deadline = deadline.replace(tzinfo=timezone.utc)
+    return deadline - EXPIRY_MARGIN <= (now or datetime.now(timezone.utc))
+
+
+class AzureDevOpsAuth:
+    """Reads the stored tokens and keeps the access token current.
+
+    One instance per provider instance; the lock keeps the executor's worker
+    threads from firing off concurrent refreshes for the same token.
+    """
+
+    def __init__(self, config: OAuthConfig, main_context: CodeeMainContext):
+        self._config = config
+        self._context = main_context
+        self._lock = threading.Lock()
+
+    def connection(self) -> dict | None:
+        """Stored token row, or None when Azure DevOps was never connected."""
+        return oauth_tokens.load_tokens(PROVIDER, main_context=self._context)
+
+    def is_connected(self) -> bool:
+        return self.connection() is not None
+
+    def disconnect(self) -> None:
+        oauth_tokens.delete_tokens(PROVIDER, main_context=self._context)
+
+    def access_token(self) -> str:
+        """A usable access token, refreshing first if the stored one is stale.
+
+        Raises AzureDevOpsAuthError when the user has to reconnect. In that case
+        the dead tokens are dropped, so the admin UI reports "not connected"
+        instead of showing a connection that can no longer fetch anything.
+        """
+        with self._lock:
+            tokens = self.connection()
+            if tokens is None:
+                raise AzureDevOpsAuthError(
+                    "Azure DevOps is not connected. Connect it in Settings.",
+                    terminal=True)
+            if not is_expired(tokens["expires_at"]):
+                return tokens["access_token"]
+
+            refresh_token = tokens.get("refresh_token")
+            if not refresh_token:
+                self.disconnect()
+                raise AzureDevOpsAuthError(
+                    "The Azure DevOps access token expired and no refresh token "
+                    "was stored. Reconnect in Settings.", terminal=True)
+
+            try:
+                fresh = refresh_access_token(self._config, refresh_token)
+            except AzureDevOpsAuthError as exc:
+                if not exc.terminal:
+                    # Entra was unreachable, throttled, or misconfigured. The
+                    # refresh token is untouched and the next poll retries it —
+                    # an outage must not cost the user a manual reconsent.
+                    raise
+                # The grant itself is dead (revoked, or aged past its 90-day
+                # window). Retrying it every poll would only hammer Entra.
+                self.disconnect()
+                raise AzureDevOpsAuthError(
+                    f"Azure DevOps authorization expired ({exc}). "
+                    "Reconnect in Settings.", terminal=True) from exc
+
+            self.store(fresh, account=tokens.get("account") or "",
+                       fallback_refresh_token=refresh_token)
+            return fresh["access_token"]
+
+    def store(
+        self,
+        tokens: dict,
+        account: str = "",
+        fallback_refresh_token: str | None = None,
+    ) -> None:
+        """Persist a token response. Keeps the previous refresh token if none came back."""
+        oauth_tokens.save_tokens(
+            PROVIDER,
+            access_token=tokens["access_token"],
+            refresh_token=tokens.get("refresh_token") or fallback_refresh_token,
+            expires_at=tokens.get("expires_at"),
+            scope=tokens.get("scope", ""),
+            account=account,
+            main_context=self._context,
+        )

codee_tasks_azure_devops/provider.py

@@ -0,0 +1,207 @@
+"""Read-only Azure DevOps tasks provider, authenticated through Entra ID.
+
+Every call here is a read: a WIQL query for the ids assigned to the connected
+account, then a batch fetch of those work items. The WIQL endpoint is a POST,
+but it is a query — nothing in this module creates or modifies a work item.
+"""
+import requests
+from codee_main_context.context import CodeeMainContext, Settings, data_dir
+from codee_tasks_abstract.provider import AbstractTasksProvider, Task
+
+from codee_tasks_azure_devops.oauth import (
+    AzureDevOpsAuth, AzureDevOpsAuthError, OAuthConfig)
+
+API_VERSION = "7.1"
+
+# Work item fields the executor and the issue-trigger matcher read.
+_FIELDS = [
+    "System.Id",
+    "System.Title",
+    "System.State",
+    "System.WorkItemType",
+    "System.Tags",
+    "System.Parent",
+    "Microsoft.VSTS.Common.Priority",
+]
+
+# The custom work item types Codee picks up, mapped to the provider-agnostic
+# issue types the executor and the issue-trigger matcher speak. Anything else
+# assigned to the connected account belongs to a human and is left alone.
+_WORK_ITEM_TYPES = {"Codee Task": "Task", "Codee Story": "Story"}
+
+# The work item type that marks a story as Codee-owned. Children of such a
+# story are driven by the story's own agent run, so the executor leaves them
+# alone — the Azure DevOps counterpart of JIRA's CodeeStory label.
+CODEE_STORY_WORK_ITEM_TYPE = "Codee Story"
+
+# Azure DevOps priority is 1-4 with 1 highest; the executor logs this next to
+# JIRA-style names, so translate rather than print a bare digit.
+_PRIORITY_NAMES = {1: "Highest", 2: "High", 3: "Medium", 4: "Low"}
+
+# Ceiling the WIQL query is capped at, matching the JIRA provider's page size.
+_MAX_TASKS = 50
+
+# Hard limit of the workitemsbatch endpoint.
+_BATCH_LIMIT = 200
+
+_TIMEOUT = 30
+
+
+def _quote_wiql(value: str) -> str:
+    """Single-quoted WIQL literal; a quote inside the value is doubled."""
+    return "'" + value.replace("'", "''") + "'"
+
+
+class AzureDevOpsWorkItem(Task):
+    """A Task that remembers the raw Azure DevOps work item type.
+
+    ``issue_type`` carries the mapped, provider-agnostic name, and that mapping
+    is lossy: a "Codee Story" and a plain "Story" both arrive as "Story".
+    Keeping the type Azure DevOps actually reported is what lets
+    ``is_parent_codee_story`` tell one parent from the other.
+    """
+
+    def __init__(self, work_item_type: str = "", **kwargs):
+        self.work_item_type = work_item_type
+        super().__init__(**kwargs)
+
+    @property
+    def is_parent_codee_story(self) -> bool:
+        """In Azure DevOps a Codee-owned story is a "Codee Story" work item."""
+        parent = self.parent
+        return (isinstance(parent, AzureDevOpsWorkItem)
+                and parent.work_item_type == CODEE_STORY_WORK_ITEM_TYPE)
+
+
+class AzureDevOpsTasksProvider(AbstractTasksProvider):
+    """Fetches work items assigned to the connected account as provider-agnostic Tasks."""
+
+    def __init__(self, settings: Settings, main_context: CodeeMainContext | None = None):
+        self._config = OAuthConfig.from_settings(settings)
+        # The executor constructs providers with settings alone, so fall back to
+        # the default data directory to reach the token store.
+        context = main_context or CodeeMainContext(data_dir=data_dir())
+        self._auth = AzureDevOpsAuth(self._config, context)
+
+    def is_configured(self) -> bool:
+        """Configured means the app details are filled in *and* OAuth completed."""
+        return self._config.is_complete() and self._auth.is_connected()
+
+    def describe(self) -> str:
+        connection = self._auth.connection() or {}
+        account = connection.get("account") or "connected account"
+        return (f"Azure DevOps {self._config.organization_url} "
+                f"(project {self._config.project}, assignee {account})")
+
+    def get_tasks(self, statuses: list[str]) -> list[Task]:
+        """Fetch work items assigned to the connected account in the given states."""
+        if not statuses:
+            return []
+        try:
+            token = self._auth.access_token()
+        except AzureDevOpsAuthError as exc:
+            print(f"Azure DevOps auth error: {exc}")
+            return []
+
+        try:
+            ids = self._query_work_item_ids(token, statuses)
+            if not ids:
+                return []
+            items = self._fetch_work_items(token, ids)
+            parents = self._fetch_parents(token, items)
+        except requests.RequestException as exc:
+            print(f"Azure DevOps API error: {exc}")
+            return []
+
+        # The batch endpoint doesn't preserve the WIQL ordering, so restore the
+        # priority-then-age order the query asked for.
+        by_id = {item["id"]: item for item in items}
+        return [self._to_task(by_id[item_id], parents)
+                for item_id in ids if item_id in by_id]
+
+    def _query_work_item_ids(self, token: str, statuses: list[str]) -> list[int]:
+        response = requests.post(
+            f"{self._config.organization_url}/{self._config.project}/_apis/wit/wiql",
+            params={"api-version": API_VERSION, "$top": _MAX_TASKS},
+            json={"query": self._build_wiql(statuses)},
+            headers=self._headers(token),
+            timeout=_TIMEOUT,
+        )
+        response.raise_for_status()
+        work_items = response.json().get("workItems") or []
+        return [item["id"] for item in work_items][:_BATCH_LIMIT]
+
+    def _build_wiql(self, statuses: list[str]) -> str:
+        """WIQL for Codee work items owned by the connected account, highest priority first."""
+        quoted_statuses = ", ".join(_quote_wiql(status) for status in statuses)
+        quoted_types = ", ".join(_quote_wiql(item_type)
+                                 for item_type in _WORK_ITEM_TYPES)
+        return (
+            "SELECT [System.Id] FROM WorkItems "
+            "WHERE [System.AssignedTo] = @Me "
+            f"AND [System.WorkItemType] IN ({quoted_types}) "
+            f"AND [System.State] IN ({quoted_statuses}) "
+            "ORDER BY [Microsoft.VSTS.Common.Priority] ASC, [System.CreatedDate] ASC"
+        )
+
+    def _fetch_work_items(self, token: str, ids: list[int]) -> list[dict]:
+        """Batch-fetch the requested work items. Organization-scoped, as the API requires."""
+        if not ids:
+            return []
+        response = requests.post(
+            f"{self._config.organization_url}/_apis/wit/workitemsbatch",
+            params={"api-version": API_VERSION},
+            json={"ids": ids[:_BATCH_LIMIT], "fields": _FIELDS},
+            headers=self._headers(token),
+            timeout=_TIMEOUT,
+        )
+        response.raise_for_status()
+        return response.json().get("value") or []
+
+    def _fetch_parents(self, token: str, items: list[dict]) -> dict[int, dict]:
+        """Resolve every referenced parent in one extra call.
+
+        Parents are fetched eagerly, unlike JIRA's deferred labels: here the
+        parent is a plain id, so there is no cheaper partial representation to
+        start from, and one batch call covers the whole page of tasks.
+        """
+        parent_ids = {
+            parent_id for parent_id in
+            (item.get("fields", {}).get("System.Parent") for item in items)
+            if parent_id
+        }
+        if not parent_ids:
+            return {}
+        parents = self._fetch_work_items(token, sorted(parent_ids))
+        return {parent["id"]: parent for parent in parents}
+
+    def _headers(self, token: str) -> dict[str, str]:
+        return {"Authorization": f"Bearer {token}",
+                "Accept": "application/json"}
+
+    def _to_task(self, item: dict, parents: dict[int, dict]) -> Task:
+        fields = item.get("fields", {})
+        parent = parents.get(fields.get("System.Parent"))
+        work_item_type = fields.get("System.WorkItemType", "")
+        return AzureDevOpsWorkItem(
+            work_item_type=work_item_type,
+            key=str(item["id"]),
+            summary=fields.get("System.Title", ""),
+            status=fields.get("System.State", ""),
+            # Parents aren't type-filtered by the query, so an unmapped type
+            # (a plain "User Story" above a Codee Task) passes through as-is.
+            issue_type=_WORK_ITEM_TYPES.get(work_item_type, work_item_type),
+            priority=_PRIORITY_NAMES.get(
+                fields.get("Microsoft.VSTS.Common.Priority"), "Unknown"),
+            labels=_split_tags(fields.get("System.Tags")),
+            # A parent's own parent is left unresolved: the executor only ever
+            # looks one level up, and chasing the chain would cost a call per level.
+            parent=self._to_task(parent, {}) if parent else None,
+        )
+
+
+def _split_tags(tags: str | None) -> list[str]:
+    """Azure DevOps returns tags as one '; '-joined string."""
+    if not tags:
+        return []
+    return [tag.strip() for tag in tags.split(";") if tag.strip()]