multi-agent-platform 0.1.0__py3-none-any.whl

server/services/errors.py

@@ -0,0 +1,65 @@
+class NotFoundError(Exception):
+    pass
+
+
+class ConflictError(Exception):
+    pass
+
+
+class BadRequestError(Exception):
+    """Caller-supplied payload is well-formed (syntactically valid JSON /
+    body) but semantically rejected — e.g. a missing cross-reference, an
+    out-of-range enum value, or a field combination that does not
+    satisfy a domain precondition. Maps to HTTP 400.
+
+    Distinct from pydantic's 422 (which fires on shape-level schema
+    failures before the handler runs).
+    """
+
+
+class UnauthorizedError(Exception):
+    pass
+
+
+class ForbiddenError(Exception):
+    pass
+
+
+class StateTransitionError(Exception):
+    """A request was structurally valid but the domain state machine refuses
+    the requested transition.
+
+    Optional attributes are surfaced to the HTTP layer by
+    :func:`server.main.register_domain_exception_handlers` so callers can
+    programmatically route on the failure mode instead of pattern-matching
+    the human-readable ``detail`` string:
+
+    - ``error_code`` — stable machine identifier (default ``"state_machine_error"``).
+      I1(d) introduces the ``REVIEW_REJECT_RESULT_MISUSE`` subcode so the
+      client can distinguish "wrong CLI command for this intent" from
+      generic state-machine refusals.
+    - ``hint`` — short remediation hint surfaced to operators and CLI users.
+    - ``retryable`` — whether the caller can succeed by retrying with the
+      same input after fixing state out-of-band. Always ``False`` for misuse
+      subcodes; preserved as a structured field for future retryable errors.
+    """
+
+    error_code: str = "state_machine_error"
+    hint: str | None = None
+    retryable: bool = False
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        error_code: str | None = None,
+        hint: str | None = None,
+        retryable: bool | None = None,
+    ) -> None:
+        super().__init__(message)
+        if error_code is not None:
+            self.error_code = error_code
+        if hint is not None:
+            self.hint = hint
+        if retryable is not None:
+            self.retryable = retryable

server/services/escalation_resolver.py

@@ -0,0 +1,248 @@
+"""STATE_MACHINE.* error escalation contact resolver (experiment 156172e9 I1(b)).
+
+Resolves which agent should be surfaced as the recovery contact when a
+STATE_MACHINE.* error fires. The lookup is two-tier:
+
+1. ``Experiment.escalation_target_agent_id`` override (set by host creator
+   on a per-experiment basis; NULL by default).
+2. Role-based fallback chain documented in plan (b):
+   a. Current caller agent (avoid cross-role mis-routing; preferred
+      since the caller usually has the most context).
+   b. Same-role + same-project active agent (any log / topic-comment /
+      review action in the last 7 days).
+   c. Admin role (last-resort).
+
+The function never raises — callers use it in error-handling paths
+where a missing escalation contact must degrade gracefully (the CLI
+falls back to printing the bare error_code + hint instead of crashing).
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+
+from map_types.enums import AgentRole
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from server.domain.models import Agent, Experiment, ExperimentLog, Review, TopicComment
+
+# Activity window for "active agent" lookup (plan (b) 2b).
+ACTIVE_LOOKBACK_DAYS = 7
+_ACTIVITY_SINCE = timedelta(days=ACTIVE_LOOKBACK_DAYS)
+
+
+def resolve_escalation_target(
+    db: Session,
+    *,
+    experiment: Experiment | None,
+    caller_agent_id: uuid.UUID | None,
+    project_id: uuid.UUID | None = None,
+) -> uuid.UUID | None:
+    """Pick the best escalation contact for a STATE_MACHINE.* error.
+
+    Returns the agent UUID, or ``None`` if no candidate exists (caller
+    should print the hint without an escalation name).
+
+    Args:
+        db: SQLAlchemy session.
+        experiment: Source experiment if available; used to read the
+            ``escalation_target_agent_id`` override.
+        caller_agent_id: Agent UUID of the CLI / SDK caller. Preferred
+            for the role-based fallback so the caller gets pinged about
+            their own action rather than a cross-role mis-route.
+        project_id: Project scope for the same-role active-agent lookup.
+            Defaults to ``experiment.project_id`` when ``experiment`` is
+            provided.
+    """
+    target_id, _tier = resolve_escalation_target_with_tier(
+        db,
+        experiment=experiment,
+        caller_agent_id=caller_agent_id,
+        project_id=project_id,
+    )
+    return target_id
+
+
+def resolve_escalation_target_with_tier(
+    db: Session,
+    *,
+    experiment: Experiment | None,
+    caller_agent_id: uuid.UUID | None,
+    project_id: uuid.UUID | None = None,
+) -> tuple[uuid.UUID | None, str]:
+    """Same as ``resolve_escalation_target`` but also returns the chosen tier.
+
+    Tiers: ``"experiment_override"`` → ``"current_caller"`` →
+    ``"same_role_active"`` → ``"admin"`` → ``"none"``. The tier is exposed
+    on ``EscalationTargetRead.tier`` so CLI / SDK callers can show the
+    user *why* a contact was chosen.
+    """
+    if experiment is not None and experiment.escalation_target_agent_id is not None:
+        return experiment.escalation_target_agent_id, "experiment_override"
+
+    scope_project_id = project_id or (experiment.project_id if experiment is not None else None)
+    if scope_project_id is None:
+        target = _admin_agent(db)
+        return target, "admin" if target is not None else "none"
+
+    # Tier 2a: the current caller (if they belong to this project).
+    caller: Agent | None = None
+    if caller_agent_id is not None:
+        caller = db.get(Agent, caller_agent_id)
+        if (
+            caller is not None
+            and caller.project_id == scope_project_id
+            and caller.role != AgentRole.admin
+        ):
+            return caller.id, "current_caller"
+
+    # Tier 2b: same-role + same-project agent with any recent activity.
+    if caller is not None and caller.project_id == scope_project_id:
+        target_role = caller.role
+        exclude_id = caller.id
+    else:
+        target_role = AgentRole.agent
+        exclude_id = caller.id if caller is not None else None
+    same_role_id = _recent_same_role_agent(
+        db,
+        project_id=scope_project_id,
+        role=target_role,
+        exclude_agent_id=exclude_id,
+    )
+    if same_role_id is not None:
+        return same_role_id, "same_role_active"
+
+    # Tier 2c: admin — prefer same-project admin, fall back to any admin.
+    target = _admin_agent(db, project_id=scope_project_id)
+    return target, "admin" if target is not None else "none"
+
+
+def _recent_same_role_agent(
+    db: Session,
+    *,
+    project_id: uuid.UUID,
+    role: AgentRole,
+    exclude_agent_id: uuid.UUID | None,
+) -> uuid.UUID | None:
+    """Return the most recently active same-role agent in the project.
+
+    "Active" = any row in ``experiment_logs`` / ``comments`` / ``reviews``
+    with ``created_at >= now - 7 days`` AND ``author_agent_id`` belongs
+    to an Agent of the requested role and project. Excludes
+    ``exclude_agent_id`` so the caller doesn't see themselves.
+
+    Tie-breaker: most recent ``created_at``. Returns ``None`` when no
+    same-role agent has any recent activity.
+
+    Implementation note: we run three small SELECTs (one per source
+    table) and pick the max ``created_at`` in Python. This avoids the
+    awkward ``CompoundSelect`` chaining for three ``union_all``s and
+    keeps the query small enough that the optimizer's row counts stay
+    predictable. The 7-day lookback bounds the row count regardless.
+    """
+    cutoff = datetime.now(UTC) - _ACTIVITY_SINCE
+
+    agents_in_project = select(Agent.id).where(
+        Agent.project_id == project_id, Agent.role == role
+    )
+    if exclude_agent_id is not None:
+        agents_in_project = agents_in_project.where(Agent.id != exclude_agent_id)
+    project_role_agents = set(db.scalars(agents_in_project).all())
+    if not project_role_agents:
+        return None
+
+    last_seen_by_agent: dict[uuid.UUID, datetime] = {}
+
+    log_rows = db.execute(
+        select(ExperimentLog.author_agent_id, ExperimentLog.created_at).where(
+            ExperimentLog.created_at >= cutoff,
+            ExperimentLog.author_agent_id.in_(project_role_agents),
+        )
+    ).all()
+    for agent_id, ts in log_rows:
+        prev = last_seen_by_agent.get(agent_id)
+        if prev is None or ts > prev:
+            last_seen_by_agent[agent_id] = ts
+
+    comment_rows = db.execute(
+        select(TopicComment.author_agent_id, TopicComment.created_at).where(
+            TopicComment.created_at >= cutoff,
+            TopicComment.author_agent_id.in_(project_role_agents),
+        )
+    ).all()
+    for agent_id, ts in comment_rows:
+        prev = last_seen_by_agent.get(agent_id)
+        if prev is None or ts > prev:
+            last_seen_by_agent[agent_id] = ts
+
+    review_rows = db.execute(
+        select(Review.reviewer_agent_id, Review.created_at).where(
+            Review.created_at >= cutoff,
+            Review.reviewer_agent_id.in_(project_role_agents),
+        )
+    ).all()
+    for agent_id, ts in review_rows:
+        prev = last_seen_by_agent.get(agent_id)
+        if prev is None or ts > prev:
+            last_seen_by_agent[agent_id] = ts
+
+    if not last_seen_by_agent:
+        return None
+    return max(last_seen_by_agent, key=lambda k: last_seen_by_agent[k])
+
+
+def _admin_agent(db: Session, *, project_id: uuid.UUID | None = None) -> uuid.UUID | None:
+    """Return an admin agent, preferring the same-project admin.
+
+    Order: same-project admin (lex order by id) → any-project admin
+    (lex order by id). Returns ``None`` when no admin exists anywhere.
+    The order is deterministic per-project — when callers need a
+    specific admin, they should set ``experiment.escalation_target_agent_id``
+    instead.
+    """
+    if project_id is not None:
+        scoped = (
+            select(Agent.id)
+            .where(Agent.role == AgentRole.admin, Agent.project_id == project_id)
+            .order_by(Agent.id)
+            .limit(1)
+        )
+        row = db.execute(scoped).first()
+        if row is not None:
+            return row[0]
+    global_admin = (
+        select(Agent.id)
+        .where(Agent.role == AgentRole.admin)
+        .order_by(Agent.id)
+        .limit(1)
+    )
+    row = db.execute(global_admin).first()
+    return row[0] if row is not None else None
+
+
+def escalation_label(
+    db: Session,
+    *,
+    escalation_target_id: uuid.UUID | None,
+) -> str:
+    """Render the escalation contact for CLI / SDK error messages.
+
+    Returns the agent name when found, or a placeholder when the agent
+    is missing (deleted / cross-project). Never raises.
+    """
+    if escalation_target_id is None:
+        return "<no escalation contact>"
+    agent = db.get(Agent, escalation_target_id)
+    if agent is None:
+        return f"<agent {escalation_target_id} not found>"
+    return f"@{agent.name}"
+
+
+__all__ = [
+    "ACTIVE_LOOKBACK_DAYS",
+    "escalation_label",
+    "resolve_escalation_target",
+    "resolve_escalation_target_with_tier",
+]

server/services/evidence_service.py

@@ -0,0 +1,88 @@
+from dataclasses import dataclass, field
+from typing import Literal
+
+from map_client.plan_evidence import (
+    PlanEvidenceKeys,
+    PlanFrontmatterParseError,
+    parse_plan_evidence_keys,
+)
+
+# arch experiment (0519e2a3) PR2: ``EVIDENCE_METADATA_KEYS`` and
+# ``metadata_has_completion_evidence`` moved to ``map_sdk.evidence``.
+# Keep them re-exported from here so existing server-side imports
+# keep working without churning every call site in this PR. CLI
+# switched to ``from map_sdk.evidence import ...`` already.
+from map_sdk.evidence import (  # noqa: E402, F401
+    EVIDENCE_METADATA_KEYS,
+    metadata_has_completion_evidence,
+)
+
+# --- 8ac93d4e I1.b — plan evidence_keys soft validation ---------------------
+
+
+WarningCode = Literal["MISSING_EVIDENCE_KEY"]
+
+
+@dataclass(frozen=True)
+class EvidenceWarning:
+    code: WarningCode
+    missing_key: str
+    plan_required: bool = True
+    log_provided: bool = False
+
+
+@dataclass(frozen=True)
+class EvidenceValidationResult:
+    warnings: list[EvidenceWarning] = field(default_factory=list)
+    parse_error: str | None = None
+    plan_keys: tuple[str, ...] = ()
+
+    @property
+    def valid(self) -> bool:
+        """Soft validation: always True. Host is expected to follow up
+        with another log if warnings indicate missing evidence."""
+        return True
+
+
+def validate_log_evidence(
+    *,
+    plan_md: str | None,
+    metadata: dict | None,
+) -> EvidenceValidationResult:
+    """Compare ``metadata`` keys against plan ``evidence_keys``.
+
+    Cases:
+    * ``plan_md`` is None or empty → empty result (no plan to validate against).
+    * Plan has frontmatter but YAML parse fails → ``parse_error`` set,
+      no warnings (caller surfaces stderr warn).
+    * Plan frontmatter OK + has ``evidence_keys`` → return
+      ``MISSING_EVIDENCE_KEY`` warning for each plan key absent from
+      ``metadata``.
+    * Plan frontmatter OK but no ``evidence_keys`` key → empty result.
+    """
+    if not plan_md:
+        return EvidenceValidationResult()
+
+    try:
+        parsed: PlanEvidenceKeys = parse_plan_evidence_keys(plan_md)
+    except PlanFrontmatterParseError as exc:
+        return EvidenceValidationResult(parse_error=str(exc))
+
+    if not parsed.keys:
+        return EvidenceValidationResult(plan_keys=parsed.keys)
+
+    provided = set(metadata.keys()) if isinstance(metadata, dict) else set()
+    warnings: list[EvidenceWarning] = []
+    for key in parsed.keys:
+        if key not in provided:
+            warnings.append(
+                EvidenceWarning(
+                    code="MISSING_EVIDENCE_KEY",
+                    missing_key=key,
+                    plan_required=True,
+                    log_provided=False,
+                )
+            )
+    return EvidenceValidationResult(warnings=warnings, plan_keys=parsed.keys)
+
+

server/services/experiment_capabilities_service.py

@@ -0,0 +1,277 @@
+"""Per-agent experiment actions and blocked_on (experiment plan v2 AC#3)."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from map_types.enums import PhaseOwner
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session, joinedload
+
+from server.domain.models import (
+    Agent,
+    AgentRole,
+    Experiment,
+    ExperimentLog,
+    ExperimentPhase,
+    Review,
+    ReviewItem,
+    ReviewItemKind,
+    ReviewItemStatus,
+)
+from server.domain.schemas import ExperimentDetailRead, ExperimentSummaryRead
+from server.services.review_service import (
+    _prior_version_reviews_fully_resolved,
+    _qualifying_non_creator_reviews,
+    _review_has_item_activity,
+    compute_legacy_self_review,
+    count_open_unreasonable_for_experiment,
+    has_review_on_older_plan_version,
+)
+
+_REPLY_STATES = (ReviewItemStatus.addressed, ReviewItemStatus.rebutted)
+
+# 0db51e10 I3(5d): phase visibility whitelist. ``hidden_for_current_persona``
+# is the per-actor fold semantics for phases excluded by the configured
+# whitelist. Empty / ``None`` whitelist = every phase visible (backward
+# compat). When a whitelist is configured, phases outside it return
+# ``([], "hidden_for_current_persona")`` so the UI can fold the row
+# without raising.
+HIDDEN_FOR_CURRENT_PERSONA = "hidden_for_current_persona"
+
+
+def _is_phase_visible(
+    phase: ExperimentPhase,
+    *,
+    phase_whitelist: list[ExperimentPhase] | None,
+) -> bool:
+    """Return True iff ``phase`` is in the configured whitelist.
+
+    ``None`` or empty whitelist = visible to every role (legacy
+    behaviour). When the whitelist is non-empty the predicate is
+    exact-match against ``phase.value`` so callers can pass either
+    ``[ExperimentPhase.result_review]`` or
+    ``["result_review"]`` interchangeably.
+    """
+    if not phase_whitelist:
+        return True
+    allowed = {p.value if isinstance(p, ExperimentPhase) else str(p) for p in phase_whitelist}
+    return phase.value in allowed
+
+
+def _reviews_for_current_plan(db: Session, experiment: Experiment) -> list[Review]:
+    return list(
+        db.scalars(
+            select(Review)
+            .where(
+                Review.experiment_id == experiment.id,
+                Review.plan_version == experiment.current_plan_version,
+            )
+            .options(joinedload(Review.items))
+        ).unique()
+    )
+
+
+def _has_non_creator_review(reviews: list[Review], creator_id: uuid.UUID) -> bool:
+    return len(_qualifying_non_creator_reviews(reviews, creator_id)) > 0
+
+
+def _actor_review_for_current_plan(reviews: list[Review], actor_id: uuid.UUID) -> Review | None:
+    for review in reviews:
+        if review.reviewer_agent_id == actor_id:
+            return review
+    return None
+
+
+def _count_open_status_unreasonable(db: Session, experiment_id: uuid.UUID) -> int:
+    stmt = (
+        select(func.count())
+        .select_from(ReviewItem)
+        .join(Review)
+        .where(
+            Review.experiment_id == experiment_id,
+            ReviewItem.kind == ReviewItemKind.unreasonable,
+            ReviewItem.status == ReviewItemStatus.open,
+        )
+    )
+    return db.scalar(stmt) or 0
+
+
+def _reviewer_has_pending_addressed_items(
+    db: Session, experiment_id: uuid.UUID, actor_id: uuid.UUID
+) -> bool:
+    stmt = (
+        select(func.count())
+        .select_from(ReviewItem)
+        .join(Review)
+        .where(
+            Review.experiment_id == experiment_id,
+            Review.reviewer_agent_id == actor_id,
+            Review.archived_at.is_(None),
+            ReviewItem.kind == ReviewItemKind.unreasonable,
+            ReviewItem.status.in_(_REPLY_STATES),
+        )
+    )
+    return (db.scalar(stmt) or 0) > 0
+
+
+def compute_experiment_capabilities(
+    db: Session,
+    experiment: Experiment,
+    actor: Agent,
+    *,
+    phase_whitelist: list[ExperimentPhase] | None = None,
+) -> tuple[list[str], str | None]:
+    is_creator = actor.id == experiment.creator_agent_id
+    is_admin = actor.role == AgentRole.admin
+    phase = experiment.phase
+
+    # 0db51e10 I3(5d): phase visibility whitelist. When configured and
+    # the current phase is NOT in the whitelist, fold the row as
+    # ``hidden_for_current_persona`` so the UI can collapse it without
+    # raising. Whitelist is dynamic — callers pass the resolved value
+    # from server config / per-test override, no module-level global.
+    if not _is_phase_visible(phase, phase_whitelist=phase_whitelist):
+        return [], HIDDEN_FOR_CURRENT_PERSONA
+
+    actions: list[str] = []
+    blocked_on: str | None = None
+
+    if phase == ExperimentPhase.result_review:
+        if is_creator:
+            return [], "awaiting_result_approval"
+        return ["accept_result", "reject_result"], "none"
+
+    if _reviewer_has_pending_addressed_items(db, experiment.id, actor.id):
+        return ["resolve_item"], "awaiting_addressed_item_ack"
+
+    if phase == ExperimentPhase.draft:
+        if is_creator or is_admin:
+            return ["submit_for_review"], "none"
+        return actions, blocked_on
+
+    if phase == ExperimentPhase.review:
+        reviews = _reviews_for_current_plan(db, experiment)
+        if is_creator or is_admin:
+            open_unreasonable = count_open_unreasonable_for_experiment(db, experiment.id)
+            if open_unreasonable > 0:
+                blocked_on = "open_unreasonable_item"
+                if _count_open_status_unreasonable(db, experiment.id) > 0:
+                    actions.append("plan_revise")
+            elif not _has_non_creator_review(reviews, experiment.creator_agent_id):
+                if _prior_version_reviews_fully_resolved(db, experiment):
+                    # Reviewer resolved every unreasonable item they raised on a
+                    # prior plan version → counts as accepting the revision, so
+                    # the creator may approve without a fresh current-version
+                    # review (mirrors assert_approve_eligibility's carve-out).
+                    blocked_on = "none"
+                    actions = ["approve", "withdraw"]
+                elif has_review_on_older_plan_version(db, experiment):
+                    blocked_on = "awaiting_review_for_current_plan_version"
+                else:
+                    blocked_on = "awaiting_non_creator_review"
+            else:
+                blocked_on = "none"
+                actions = ["approve", "withdraw"]
+            return actions, blocked_on
+
+        if actor.id != experiment.creator_agent_id:
+            actor_review = _actor_review_for_current_plan(reviews, actor.id)
+            if actor_review is None:
+                return ["review_add"], "none"
+            if not _review_has_item_activity(actor_review):
+                return ["review_withdraw"], "none"
+        return actions, blocked_on
+
+    if is_creator or is_admin:
+        if phase == ExperimentPhase.approved:
+            return ["start"], "none"
+        if phase == ExperimentPhase.running:
+            return ["complete"], "none"
+
+    return actions, blocked_on
+
+
+def experiment_summary_for_actor(
+    db: Session,
+    experiment: Experiment,
+    actor: Agent,
+    *,
+    extra_updates: dict[str, Any] | None = None,
+    phase_whitelist: list[ExperimentPhase] | None = None,
+) -> ExperimentSummaryRead:
+    from server.services.log_service import get_latest_log
+    from server.services.phase_owner_resolver import (
+        is_informational_only,
+        owner_for,
+    )
+
+    actions, blocked_on = compute_experiment_capabilities(
+        db, experiment, actor, phase_whitelist=phase_whitelist
+    )
+    legacy = compute_legacy_self_review(db, experiment)
+    # log_count / latest_log_summary: skip the per-experiment SELECTs
+    # when extra_updates already provides them — looping callers (e.g.
+    # get_todos over many experiments) pre-compute via the bulk helpers
+    # in log_service to drop the N+1.
+    has_log_count = extra_updates is not None and "log_count" in extra_updates
+    has_latest_summary = (
+        extra_updates is not None and "latest_log_summary" in extra_updates
+    )
+    if has_log_count:
+        log_count: int = extra_updates["log_count"]
+    else:
+        log_count = (
+            db.scalar(
+                select(func.count())
+                .select_from(ExperimentLog)
+                .where(ExperimentLog.experiment_id == experiment.id)
+            )
+            or 0
+        )
+    if has_latest_summary:
+        latest_log_summary: str | None = extra_updates["latest_log_summary"]
+    else:
+        latest_log = get_latest_log(db, experiment.id)
+        latest_log_summary = latest_log.summary if latest_log else None
+
+    update: dict[str, Any] = {
+        "actions": actions,
+        "blocked_on": blocked_on,
+        "legacy_self_review": legacy,
+        "log_count": log_count,
+        "latest_log_summary": latest_log_summary,
+        "phase_owner": owner_for(experiment.phase),
+        "informational_only": is_informational_only(
+            experiment.phase, actions=actions, blocked_on=blocked_on
+        ),
+        "hidden_for_current_persona": (
+            actions == []
+            and blocked_on == HIDDEN_FOR_CURRENT_PERSONA
+        ),
+    }
+    if extra_updates:
+        update.update(extra_updates)
+    return ExperimentSummaryRead.model_validate(experiment).model_copy(update=update)
+
+
+def apply_capabilities_to_detail(
+    detail: ExperimentDetailRead,
+    actions: list[str],
+    blocked_on: str | None,
+    *,
+    legacy_self_review: bool = False,
+    phase_owner: PhaseOwner | None = None,
+    informational_only: bool | None = None,
+) -> ExperimentDetailRead:
+    update: dict[str, Any] = {
+        "actions": actions,
+        "blocked_on": blocked_on,
+        "legacy_self_review": legacy_self_review,
+    }
+    if phase_owner is not None:
+        update["phase_owner"] = phase_owner
+    if informational_only is not None:
+        update["informational_only"] = informational_only
+    return detail.model_copy(update=update)