taskboy 0.1.1__py3-none-any.whl

taskboy/audit.py

@@ -0,0 +1,78 @@
+"""audit trail tamper-evidence and off-host shipping (§10).
+
+every task_event carries a hash chained to the previous event (computed in store._insert_event);
+verify_chain recomputes it. ship_once exports new events as jsonl to the object-locked s3 bucket,
+so even a compromised host cannot rewrite history that has already shipped.
+"""
+
+import asyncio
+import json
+import logging
+
+from taskboy.store import Store, admin_event_hash, event_hash
+
+logger = logging.getLogger("taskboy.audit")
+
+
+def verify_chain(store: Store) -> tuple[bool, int]:
+    """recompute the hash chain; returns (intact, events_checked). rows predating the hash column are skipped."""
+    prev = ""
+    checked = 0
+    for row in store.events_after(0, limit=1_000_000):
+        if row["hash"] is not None:
+            expected = event_hash(prev, row["ts"], row["task_id"], row["kind"], row["tool_name"], row["detail_json"])
+            if row["hash"] != expected:
+                logger.error("audit chain broken at event id %s", row["id"])
+                return False, checked
+            checked += 1
+        prev = row["hash"] or ""
+    return True, checked
+
+
+async def ship_once(store: Store, bucket: str, prefix: str = "audit") -> int:
+    """upload events newer than the last shipped id; the meta cursor makes retries idempotent.
+
+    sqlite stays on the event-loop thread (the connection is not shareable across threads);
+    only the s3 upload runs in a worker.
+    """
+    last_shipped = int(store.meta_get("audit_shipped_id") or 0)
+    events = store.events_after(last_shipped)
+    if not events:
+        return 0
+    key = f"{prefix}/events-{events[0]['id']:012d}-{events[-1]['id']:012d}.jsonl"
+    await asyncio.to_thread(_put, bucket, key, "\n".join(json.dumps(event) for event in events))
+    store.meta_set("audit_shipped_id", str(events[-1]["id"]))
+    logger.info("shipped %s audit events to s3://%s/%s", len(events), bucket, key)
+    return len(events)
+
+
+def verify_admin_chain(store: Store) -> tuple[bool, int]:
+    prev = ""
+    checked = 0
+    for row in store.admin_events_after(0, limit=1_000_000):
+        expected = admin_event_hash(prev, row["ts"], row["actor"], row["action"], row["target"], row["outcome"], row["detail_json"])
+        if row["hash"] != expected:
+            logger.error("admin audit chain broken at event id %s", row["id"])
+            return False, checked
+        prev = row["hash"]
+        checked += 1
+    return True, checked
+
+
+async def ship_admin_once(store: Store, bucket: str, prefix: str = "admin-audit") -> int:
+    last_shipped = int(store.meta_get("admin_audit_shipped_id") or 0)
+    events = store.admin_events_after(last_shipped)
+    if not events:
+        return 0
+    key = f"{prefix}/events-{events[0]['id']:012d}-{events[-1]['id']:012d}.jsonl"
+    await asyncio.to_thread(_put, bucket, key, "\n".join(json.dumps(event) for event in events))
+    store.meta_set("admin_audit_shipped_id", str(events[-1]["id"]))
+    logger.info("shipped %s admin audit events to s3://%s/%s", len(events), bucket, key)
+    return len(events)
+
+
+def _put(bucket: str, key: str, body: str) -> None:
+    """the s3 seam — patched in unit tests."""
+    import boto3
+
+    boto3.client("s3").put_object(Bucket=bucket, Key=key, Body=body.encode())

taskboy/broker.py

@@ -0,0 +1,266 @@
+"""credential broker: short-lived, down-scoped github app installation tokens per task (GIT-014, TOL-007, EC2-009).
+
+sub-agents never hold a long-lived credential. git asks this broker at use-time through a
+credential helper over a unix socket, authenticated by a per-task nonce; the broker mints an
+installation token scoped to the task's profile (read-only vs write) and target repositories,
+caches it, and re-mints when close to expiry — so github's ~1h ttl never breaks a long task.
+task A's nonce is useless for task B, and every minted token is registered with the redactor.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import secrets as pysecrets
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+import jwt
+
+from taskboy.adapters.github_api import GitHubStatusError
+from taskboy.models import Task
+from taskboy.redact import redactor
+
+logger = logging.getLogger("taskboy.broker")
+
+GITHUB_API = "https://api.github.com"
+REFRESH_MARGIN_SECONDS = 600  # re-mint when less than 10 minutes remain
+
+# github app permissions requested per routing profile: allowlist, hook, and credential all agree (§8.4)
+PROFILE_PERMISSIONS = {
+    "read_only": {"contents": "read", "metadata": "read", "pull_requests": "read"},
+    "standard": {"contents": "write", "metadata": "read", "pull_requests": "write"},
+    "deep": {"contents": "write", "metadata": "read", "pull_requests": "write"},
+}
+
+
+@dataclass
+class TaskGrant:
+    task_id: str
+    nonce: str
+    repositories: list[str]  # short repo names (github's api takes names, not org/name)
+    permissions: dict
+    token: str | None = field(default=None, repr=False)
+    expires_at: float = 0.0
+
+
+class CredentialBroker:
+    def __init__(self, app_id: str, installation_id: str, private_key: str, socket_path: str, helper_path: str):
+        self.app_id = app_id
+        self.installation_id = installation_id
+        self.private_key = private_key
+        self.socket_path = socket_path
+        self.helper_path = helper_path
+        self.grants: dict[str, TaskGrant] = {}
+        self._nonce_index: dict[str, str] = {}
+        self._server: asyncio.AbstractServer | None = None
+        self._app_slug_cache: str | None = None
+        self.accessible_repos: set[str] | None = None  # short names; None = never discovered (disables the 422 fallback)
+
+    # -- task lifecycle --------------------------------------------------------
+
+    def register_task(self, task: Task, approved_repos: list[str], granted_repos: list[str] | None = None, *, hooks_path: str) -> dict[str, str]:
+        """returns the env vars for the task session; the future token is scoped to profile + target repos.
+
+        granted_repos are repos an operator approved mid-task; they widen the token scope beyond the task's
+        original classification so live git ops against a granted repo authenticate instead of 403ing (§8.4)."""
+        permissions = PROFILE_PERMISSIONS.get(task.profile or "", PROFILE_PERMISSIONS["read_only"])
+        targets = (json.loads(task.classification_json) if task.classification_json else {}).get("target_repos") or []
+        repos = [repo for repo in targets if repo in approved_repos]
+        for repo in granted_repos or []:
+            if repo in approved_repos and repo not in repos:
+                repos.append(repo)
+        repos = repos or list(approved_repos)
+        nonce = pysecrets.token_urlsafe(32)
+        redactor.register(nonce)
+        self.grants[task.task_id] = TaskGrant(task.task_id, nonce, [repo.split("/", 1)[-1] for repo in repos], permissions)
+        self._nonce_index[nonce] = task.task_id
+        return {
+            "TASKBOY_BROKER_SOCKET": self.socket_path,
+            "TASKBOY_TASK_NONCE": nonce,
+            "GIT_TERMINAL_PROMPT": "0",
+            "GIT_CONFIG_COUNT": "2",
+            "GIT_CONFIG_KEY_0": "credential.helper",
+            "GIT_CONFIG_VALUE_0": self.helper_path,
+            # every repo the session touches — mirror-seeded or agent-cloned — runs the workspace pre-push hook (#95)
+            "GIT_CONFIG_KEY_1": "core.hooksPath",
+            "GIT_CONFIG_VALUE_1": hooks_path,
+        }
+
+    def release_task(self, task_id: str) -> None:
+        grant = self.grants.pop(task_id, None)
+        if grant is None:
+            return
+        self._nonce_index.pop(grant.nonce, None)
+        redactor.unregister(grant.nonce)
+        redactor.unregister(grant.token)
+
+    async def verify(self, approved_repos: list[str] | None = None) -> None:
+        """startup probe: mint a minimal token so app-id/key/installation problems surface at boot, not mid-task.
+
+        also snapshots which of approved_repos the installation can actually see, so a stale
+        config.yaml entry gets a clear warning now instead of a raw 422 mid-task (§8.4)."""
+        data = await self._mint_token({"permissions": {"metadata": "read"}})
+        token = str(data.get("token"))
+        redactor.register(token)
+        self.accessible_repos = await self._discover_accessible_repos(token)
+        if self.accessible_repos is not None:
+            for repo in approved_repos or []:
+                if repo.split("/", 1)[-1] not in self.accessible_repos:
+                    logger.warning(
+                        "github.approved_repos entry %s is not accessible to this GitHub App installation — install the app on it or remove it from approved_repos",
+                        repo,
+                    )
+
+    async def _discover_accessible_repos(self, token: str) -> set[str] | None:
+        """paginated GET /installation/repositories; returns None (disabling the fallback) if listing fails."""
+        try:
+            accessible: set[str] = set()
+            page = 1
+            while page <= 10:
+                result = await self._get_github(f"/installation/repositories?per_page=100&page={page}", token)
+                entries = result.get("repositories") or []
+                accessible.update(str(entry["name"]) for entry in entries if entry.get("name"))
+                if len(entries) < 100:
+                    break
+                page += 1
+            return accessible
+        except Exception as e:
+            logger.warning("failed to list installation repositories — approved_repos drift check disabled: %s", e)
+            return None
+
+    async def read_token(self, repositories: list[str], permissions: dict | None = None) -> tuple[str, float]:
+        """fetch-only installation token for the mirror cache (contents:read, metadata:read).
+
+        returns (token, expires_at_epoch), using github's actual expiry when present."""
+        payload: dict = {"permissions": permissions if permissions is not None else {"contents": "read", "metadata": "read"}}
+        if repositories:
+            payload["repositories"] = [repo.split("/", 1)[-1] for repo in repositories]
+        data = await self._mint_token(payload)
+        token = str(data["token"])
+        redactor.register(token)
+        expires_at = _parse_expiry(data.get("expires_at")) or time.time() + 55 * 60
+        return token, expires_at
+
+    async def app_slug(self) -> str:
+        if self._app_slug_cache is None:
+            data = await self._get_github("/app", self._app_jwt())
+            slug = str(data.get("slug") or "")
+            if not slug:
+                raise RuntimeError("github app response did not include a slug")
+            self._app_slug_cache = slug
+        return self._app_slug_cache
+
+    # -- token minting -----------------------------------------------------------
+
+    async def credentials_for_nonce(self, nonce: str) -> dict:
+        task_id = self._nonce_index.get(nonce)
+        if task_id is None:
+            raise PermissionError("unknown task nonce")
+        return {"username": "x-access-token", "password": await self.token_for_task(task_id)}
+
+    async def token_for_task(self, task_id: str) -> str:
+        grant = self.grants.get(task_id)
+        if grant is None:
+            raise PermissionError(f"no credential grant for task {task_id}")
+        if grant.token is None or grant.expires_at - time.time() < REFRESH_MARGIN_SECONDS:
+            await self._mint(grant)
+        assert grant.token is not None
+        return grant.token
+
+    async def _mint(self, grant: TaskGrant) -> None:
+        payload: dict = {"permissions": grant.permissions}
+        if grant.repositories:
+            payload["repositories"] = grant.repositories
+        data = await self._mint_token(payload)
+        redactor.unregister(grant.token)
+        grant.token = str(data["token"])
+        grant.expires_at = _parse_expiry(data.get("expires_at")) or time.time() + 55 * 60
+        redactor.register(grant.token)
+        logger.info("minted github token for %s (repos=%s, perms=%s)", grant.task_id, grant.repositories, grant.permissions)
+
+    async def _mint_token(self, payload: dict) -> dict:
+        """mint an installation token; on a 422 caused by inaccessible repos, retry with only accessible ones."""
+        try:
+            return await self._post_github(f"/app/installations/{self.installation_id}/access_tokens", self._app_jwt(), payload)
+        except GitHubStatusError as e:
+            requested = payload.get("repositories")
+            if e.status != 422 or not requested or self.accessible_repos is None or "not accessible" not in str(e):
+                raise
+            usable = [repo for repo in requested if repo in self.accessible_repos]
+            if not usable:
+                raise RuntimeError(f"the GitHub App is not installed on {', '.join(requested)} — install it on those repositories or remove them from github.approved_repos") from e
+            if usable == list(requested):
+                raise  # 422 was not about our repo list after all
+            logger.warning("token mint 422ed; retrying without inaccessible repos %s", sorted(set(requested) - set(usable)))
+            return await self._post_github(f"/app/installations/{self.installation_id}/access_tokens", self._app_jwt(), {**payload, "repositories": usable})
+
+    def _app_jwt(self) -> str:
+        now = int(time.time())
+        return jwt.encode({"iat": now - 60, "exp": now + 540, "iss": str(self.app_id)}, self.private_key, algorithm="RS256")
+
+    async def _post_github(self, path: str, bearer: str, payload: dict) -> dict:
+        """the http seam — patched in unit tests."""
+        import aiohttp
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(GITHUB_API + path, json=payload, headers={"Authorization": f"Bearer {bearer}", "Accept": "application/vnd.github+json"}) as response:
+                if response.status >= 300:
+                    body = redactor.redact(await response.text())[:300]
+                    raise GitHubStatusError(response.status, f"github token mint failed: {response.status} — {body}")
+                return await response.json()
+
+    async def _get_github(self, path: str, bearer: str) -> dict:
+        """the app-metadata http seam — patched in unit tests."""
+        import aiohttp
+
+        async with aiohttp.ClientSession() as session:
+            async with session.get(GITHUB_API + path, headers={"Authorization": f"Bearer {bearer}", "Accept": "application/vnd.github+json"}) as response:
+                if response.status >= 300:
+                    body = redactor.redact(await response.text())[:300]
+                    raise RuntimeError(f"github api GET {path} failed: {response.status} — {body}")
+                return await response.json()
+
+    # -- unix socket server -------------------------------------------------------
+
+    async def start(self) -> None:
+        path = Path(self.socket_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.unlink(missing_ok=True)
+        self._server = await asyncio.start_unix_server(self._handle, path=self.socket_path)
+        os.chmod(self.socket_path, 0o666)  # task slot users must be able to connect; the nonce is the auth
+
+    async def stop(self) -> None:
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+        Path(self.socket_path).unlink(missing_ok=True)
+
+    async def _handle(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            request = json.loads(await reader.readline())
+            if request.get("op") == "git-credentials":
+                response = await self.credentials_for_nonce(str(request.get("nonce", "")))
+            else:
+                response = {"error": "unknown op"}
+        except PermissionError as e:
+            response = {"error": str(e)}
+        except Exception as e:
+            logger.exception("broker request failed")
+            response = {"error": redactor.redact(str(e))}
+        try:
+            writer.write((json.dumps(response) + "\n").encode())
+            await writer.drain()
+        finally:
+            writer.close()
+
+
+def _parse_expiry(value) -> float | None:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        return None

taskboy/classifier.py

@@ -0,0 +1,219 @@
+"""task classification: one small structured-output model call, then config-driven routing (MOD-001/002).
+
+failures never guess silently: one retry, then the fixed fallback classification, always audited (MOD-005/009).
+"""
+
+import json
+import logging
+import re
+
+from taskboy import settings, skills
+from taskboy.config import Config, ConfigError, Role, role_for
+from taskboy.llm import _extract_json, extract_usage, structured_call  # noqa: F401  (extract_usage re-exported for callers/tests)
+from taskboy.models import EFFORT_LEVELS, Task
+from taskboy.prompts import CLASSIFICATION_SCHEMA, classifier_prompt, trim_context
+from taskboy.router import RoleRefusal, RoutingDecision, route, route_skill
+from taskboy.store import Store
+
+logger = logging.getLogger("taskboy.classifier")
+
+FALLBACK_CLASSIFICATION = {
+    "task_type": "investigation",
+    "complexity": "standard",
+    "risk": "read_only",
+    "expected_duration": "under_hour",
+    "required_integrations": [],
+    "target_repos": [],
+    "jira_keys": [],
+}
+
+# "effort" is optional in CLASSIFICATION_SCHEMA (never a hard failure), but a stray/unrecognized value from a
+# stored triage classification or a lenient model call should be dropped rather than reach the router (MOD-009)
+VALID_EFFORT_VALUES = set(EFFORT_LEVELS) | {"auto"}
+
+# issue #55: prompt guidance (classification_guidance() in prompts.py) tells the model that
+# "address/fix/respond to/resolve review comments on a PR" is bug_fix, not pr_review — but a
+# haiku-tier classifier following prose isn't reliable on plural/no-URL phrasings, so this is
+# re-checked deterministically after the model call, before routing, and always audited.
+# matches either order — "address ... comments" and "comments ... resolve them" both trigger,
+# since same-intent requests routinely put the verb after the noun (issue #55 follow-up).
+_REVIEW_COMMENTS_VERB_RE = re.compile(
+    r"\b(address|fix|respond to|resolve)\b.{0,40}\b(review )?comments\b" r"|\b(review )?comments\b.{0,40}\b(address|fix|respond to|resolve)\b",
+    re.IGNORECASE | re.DOTALL,
+)
+_PR_REFERENCE_RE = re.compile(r"\bPRs?\b|\bpull requests?\b|/pull/\d+", re.IGNORECASE)
+
+
+def _apply_review_comments_guard(classification: dict, request_text: str) -> tuple[dict, str | None]:
+    """returns the (possibly overridden) classification and a guard name to audit, or None if untouched."""
+    if classification.get("task_type") != "pr_review":
+        return classification, None
+    if not (_REVIEW_COMMENTS_VERB_RE.search(request_text) and _PR_REFERENCE_RE.search(request_text)):
+        return classification, None
+    overridden = {**classification, "task_type": "bug_fix", "risk": "writes_code"}
+    return overridden, "review-comments-override"
+
+
+async def stub_classify(task: Task) -> dict:
+    """dev/echo-mode classifier: no model call, fixed fields."""
+    return {"task_type": "investigation", "complexity": "standard", "routing_rationale": "stub classifier"}
+
+
+class Classifier:
+    def __init__(self, store: Store, config: Config):
+        self.store = store
+        self.config = config
+        tier = (config.raw.get("classifier") or {}).get("tier", "haiku")
+        models = config.raw.get("models") or {}
+        if tier not in models:
+            raise ConfigError(f"classifier.tier {tier!r} is not in the model catalog")
+        self.model_alias = tier
+        self.model_id = str(models[tier]["id"])
+
+    async def classify(self, task: Task) -> dict:
+        return await self._classify(task)
+
+    async def _classify(self, task: Task) -> dict:
+        """returns the task fields set when the task moves received -> queued."""
+        role = role_for(self.config.roles, task.slack_user_id)
+        if role is None:
+            raise RoleRefusal(f"user {task.slack_user_id!r} has no configured role")
+        invocation = skills.parse_invocation(task.request_text)
+        if invocation and invocation[0] in skills.available(settings.SKILLS_ROOT):
+            name, args = invocation
+            skill_config = self.config.raw.get("skills") or {}
+            loaded = skills.load(settings.SKILLS_ROOT, name)
+            profile = str(loaded.profile or skill_config.get("profile", "standard"))
+            approved_repos = ((self.config.raw.get("github") or {}).get("approved_repos") or []) if self.config.service_enabled("github") else []
+            if role.repos is not None:
+                approved_repos = [repo for repo in approved_repos if repo in role.repos]
+            target_repos = []
+            for repo in approved_repos:
+                short_name = repo.split("/", 1)[-1]
+                if re.search(rf"(?<![a-z0-9_-]){re.escape(short_name)}(?![a-z0-9_-])", args, flags=re.IGNORECASE):
+                    target_repos.append(repo)
+            classification: dict = {
+                "task_type": "skill",
+                "complexity": "standard",
+                "risk": "read_only" if profile == "read_only" else "writes_code_and_jira",
+                "expected_duration": "hours",
+                "required_integrations": [],
+                "target_repos": target_repos,
+                "jira_keys": [],
+                "skill": name,
+                "skill_args": args,
+                "skill_internal_tools": loaded.internal_tools,
+            }
+            decision = route_skill(task.model_override, self.config.raw, role=role, skill_tier=loaded.model, skill_profile=loaded.profile)
+            self.store.add_event(task.task_id, "classified", {**classification, "fallback": False})
+            self.store.add_event(task.task_id, "model_routing", {"model_alias": decision.model_alias, "model_id": decision.model_id, "profile": decision.profile, "rationale": decision.rationale})
+            return _task_fields(classification, decision, _review_persona(classification, self.config.reviewer.enabled))
+        if task.classification_json:
+            try:
+                stored = json.loads(task.classification_json)
+                classification = validate_classification(stored)
+            except (TypeError, ValueError, json.JSONDecodeError):
+                pass
+            else:
+                classification, guard = _apply_review_comments_guard(classification, task.request_text)
+                decision = route(classification["task_type"], classification["complexity"], task.model_override, self.config.raw, role=role, classifier_effort=classification.get("effort"))
+                detail = {**classification, "fallback": False, "source": "triage"}
+                if guard:
+                    detail["guard"] = guard
+                self.store.add_event(task.task_id, "classified", detail)
+                self.store.add_event(task.task_id, "model_routing", {"model_alias": decision.model_alias, "model_id": decision.model_id, "profile": decision.profile, "rationale": decision.rationale})
+                return _task_fields(classification, decision, _review_persona(classification, self.config.reviewer.enabled))
+        classification, usage, fell_back = await self._classify_once(task, role)
+        classification, guard = _apply_review_comments_guard(classification, task.request_text)
+        decision = route(classification["task_type"], classification["complexity"], task.model_override, self.config.raw, role=role, classifier_effort=classification.get("effort"))
+        detail = {**classification, "fallback": fell_back}
+        if guard:
+            detail["guard"] = guard
+        self.store.add_event(task.task_id, "classified", detail)
+        self.store.add_event(task.task_id, "model_routing", {"model_alias": decision.model_alias, "model_id": decision.model_id, "profile": decision.profile, "rationale": decision.rationale})
+        if usage:
+            self.store.add_usage(task.task_id, "classifier", self.model_id, **usage)
+        return _task_fields(classification, decision, _review_persona(classification, self.config.reviewer.enabled))
+
+    async def _classify_once(self, task: Task, role: Role | None = None) -> tuple[dict, dict | None, bool]:
+        github = (self.config.raw.get("github") or {}) if self.config.service_enabled("github") else {}
+        approved_repos = github.get("approved_repos") or []
+        if role is not None and role.repos is not None:
+            approved_repos = [repo for repo in approved_repos if repo in role.repos]
+        self_repo = str(github.get("self_repo") or "")
+        prompt = classifier_prompt(
+            task.request_text,
+            approved_repos,
+            self.config.enabled_integrations(),
+            trim_context(task.thread_context),
+            self_repo=self_repo if self_repo in approved_repos else None,
+            bot_name=self.config.agent_name,
+        )
+        # structured_call already retries once internally, so one call here bounds the worst case at two model calls before fallback
+        try:
+            classification, usage = await self._call_model(prompt)
+            return classification, usage, False
+        except Exception as e:
+            logger.warning("classifier call failed for %s: %s", task.task_id, e)
+            self.store.add_event(task.task_id, "classifier_failed", {"what": "classifier", "error": str(e)})
+            self.store.add_error("classifier", type(e).__name__, str(e), task_id=task.task_id)
+        return dict(FALLBACK_CLASSIFICATION), None, True
+
+    async def _call_model(self, prompt: str) -> tuple[dict, dict | None]:
+        """the per-call API seam — patched in unit tests."""
+        classification, usage = await structured_call(self.model_id, prompt, CLASSIFICATION_SCHEMA)
+        return validate_classification(classification), usage
+
+
+def _review_persona(classification: dict, reviewer_enabled: bool) -> str | None:
+    """only a genuine /review skill invocation runs as the reviewer: a model-labeled pr_review can be a
+    misclassified "address the review comments" request, which writes code and must stay with the main agent."""
+    if reviewer_enabled and classification.get("skill") == "review":
+        return "reviewer"
+    return None
+
+
+def _task_fields(classification: dict, decision: RoutingDecision, persona: str | None = None) -> dict:
+    fields = {
+        "classification_json": json.dumps(classification),
+        "task_type": classification["task_type"],
+        "complexity": classification["complexity"],
+        "risk": classification["risk"],
+        "model_alias": decision.model_alias,
+        "model_id": decision.model_id,
+        "profile": decision.profile,
+        "routing_rationale": decision.rationale,
+        "max_budget_usd": decision.max_budget_usd,
+        "max_turns": decision.max_turns,
+        "max_runtime_minutes": decision.max_runtime_minutes,
+        "effort": decision.effort,
+    }
+    if persona is not None:
+        fields["persona"] = persona
+    return fields
+
+
+def validate_classification(candidate) -> dict:
+    """lenient: only task_type/complexity are fatal (no safe default); other missing fields fill from FALLBACK_CLASSIFICATION."""
+    if not isinstance(candidate, dict):
+        raise ValueError("classifier returned no structured output")
+    missing = [key for key in CLASSIFICATION_SCHEMA["required"] if key not in candidate]
+    if "task_type" in missing or "complexity" in missing:
+        raise ValueError(f"classification missing fields: {missing}")
+    if missing:
+        logger.info("classification filled missing fields %s with defaults", missing)
+    filled = dict(candidate)
+    for key in missing:
+        filled[key] = FALLBACK_CLASSIFICATION[key]
+    if "effort" in filled and filled["effort"] not in VALID_EFFORT_VALUES:
+        filled.pop("effort")
+    return filled
+
+
+def parse_classification(message) -> dict:
+    """tolerant of sdk result shapes: structured_output attr, json in result, or json embedded in prose."""
+    candidate = getattr(message, "structured_output", None)
+    if candidate is None:
+        result = getattr(message, "result", None)
+        candidate = _extract_json(result) if isinstance(result, str) else result
+    return validate_classification(candidate)