marvisx-cli 0.1.0__py3-none-any.whl

core/api/services/audit.py

@@ -0,0 +1,58 @@
+# v1.0.0 - 2026-03-03 - Audit logging for privileged human operations
+"""
+Audit logging service.
+
+Writes immutable records to the audit_log table for human-only privileged
+operations: PR merge/revert, task approve/complete, delete operations, user
+management actions.
+
+Non-critical: failures are logged as warnings but never block the caller.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+
+async def log_audit(
+    db: aiosqlite.Connection,
+    action: str,
+    user: str,
+    resource_type: str,
+    resource_id: str,
+    details: dict[str, Any] | None = None,
+) -> None:
+    """Write one audit record to the audit_log table.
+
+    Args:
+        db:            Active aiosqlite connection (request-scoped or fresh).
+        action:        Verb describing the privileged operation, e.g.
+                       "pr.merge", "task.approve", "task.delete", "user.delete".
+        user:          Username (or agent slug) performing the action.
+        resource_type: Entity type: "pull_request", "task", "user", "raci", etc.
+        resource_id:   Primary key of the affected resource.
+        details:       Optional free-form dict serialised to JSON for extra context.
+
+    Non-critical: any exception is caught and logged as a warning so the
+    caller's business logic is never interrupted by an audit failure.
+    """
+    try:
+        await db.execute(
+            "INSERT INTO audit_log (action, user, resource_type, resource_id, details_json) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (
+                action,
+                user,
+                resource_type,
+                resource_id,
+                json.dumps(details) if details is not None else None,
+            ),
+        )
+        await db.commit()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("log_audit failed (non-critical): %s", exc)

core/api/services/auto_approval.py

@@ -0,0 +1,82 @@
+# v1.3.0 - 2026-05-28 - Self-improvement veto agent list is config-driven (SELF_IMPROVEMENT_AGENTS)
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from enum import Enum
+
+from core.api.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+class ApprovalDecision(str, Enum):
+    AUTO_APPROVED = "auto_approved"
+    PENDING_HUMAN = "pending"
+
+
+@dataclass
+class ApprovalPolicy:
+    """Evaluate whether a new task should be auto-approved or require human review.
+
+    Safety valves:
+    - Impact veto: high-impact tasks always need human review
+    - Confidence floor: low-confidence scores need human review
+    - Daily cap: checked externally (not in this class)
+    """
+
+    agent_ease_threshold: int = 6
+    hybrid_ease_threshold: int = 7
+    impact_veto_threshold: int = 9
+    min_confidence: int = 5
+
+    def evaluate(
+        self,
+        delegation: str | None,
+        ease: int | None,
+        impact: int | None,
+        confidence: int | None,
+        scored_by: str | None,
+        created_by: str | None,
+    ) -> tuple[ApprovalDecision, str]:
+        """Return (decision, reason) for a task's initial status."""
+
+        # Unscored tasks always need human review
+        if delegation is None or ease is None:
+            return ApprovalDecision.PENDING_HUMAN, "unscored_task"
+
+        # Self-improvement hybrid proposals always require human review.
+        # The agent list is config-driven (SELF_IMPROVEMENT_AGENTS) so OSS core
+        # ships no internal agent names; our deploy .env arms the veto. Read
+        # settings live so tests can override via monkeypatch.
+        if (
+            created_by is not None
+            and created_by in settings.self_improvement_agents
+            and delegation == "hybrid"
+        ):
+            return ApprovalDecision.PENDING_HUMAN, "agent_self_improvement_hybrid_veto"
+
+        # Human delegation = human IS the gate, auto-approve
+        if delegation == "human":
+            return ApprovalDecision.AUTO_APPROVED, "delegation_human"
+
+        # Safety valve: high impact always needs human eyes
+        if impact is not None and impact >= self.impact_veto_threshold:
+            return ApprovalDecision.PENDING_HUMAN, "high_impact_veto"
+
+        # Safety valve: low confidence = uncertain, needs human
+        if confidence is not None and confidence < self.min_confidence:
+            return ApprovalDecision.PENDING_HUMAN, "low_confidence"
+
+        # Threshold-based auto-approval
+        if delegation == "agent" and ease >= self.agent_ease_threshold:
+            return ApprovalDecision.AUTO_APPROVED, "agent_ease_threshold"
+
+        if delegation == "hybrid" and ease >= self.hybrid_ease_threshold:
+            return ApprovalDecision.AUTO_APPROVED, "hybrid_ease_threshold"
+
+        return ApprovalDecision.PENDING_HUMAN, "below_threshold"
+
+
+# Singleton — can be overridden per-project via project.yaml thresholds
+DEFAULT_POLICY = ApprovalPolicy()

core/api/services/brain/__init__.py

@@ -0,0 +1,52 @@
+# Brain v1 — Digest + Journal subpackage (sub-01).
+# Layering: api/models/brain.py owns cross-boundary contracts.
+# Service-private dataclasses live in api/services/brain/models.py.
+# No LLM imports allowed at this layer (parent §9.3 invariant).
+from __future__ import annotations
+
+from core.api.services.brain.cycle import (
+    canonical_evidence,
+    cycle_cutoff_at,
+    current_brain_cycle_key,
+    derive_event_id,
+    evidence_hash as compute_evidence_hash,
+    make_event_id,
+    persist_event,
+    polish_pending_journals,
+    polish_run_journals,
+    publish_run_journals,
+    update_run_status,
+)
+from core.api.services.brain.capabilities import KNOWLEDGE_GLYPHS, get_capabilities
+from core.api.services.brain.events_reader import list_events_for_cycle
+from core.api.services.brain.jobs import recompute_brain_cycle, run_brain_jobs_if_due
+from core.api.services.brain.runs_reader import (
+    fetch_single_run,
+    get_pipeline_counters,
+    list_runs,
+)
+from core.api.services.brain.ws_emitter import emit_phase_complete, get_hub
+
+__all__ = [
+    "KNOWLEDGE_GLYPHS",
+    "canonical_evidence",
+    "compute_evidence_hash",
+    "current_brain_cycle_key",
+    "cycle_cutoff_at",
+    "derive_event_id",
+    "emit_phase_complete",
+    "fetch_single_run",
+    "get_capabilities",
+    "get_hub",
+    "get_pipeline_counters",
+    "list_events_for_cycle",
+    "list_runs",
+    "make_event_id",
+    "persist_event",
+    "polish_pending_journals",
+    "polish_run_journals",
+    "publish_run_journals",
+    "recompute_brain_cycle",
+    "run_brain_jobs_if_due",
+    "update_run_status",
+]

core/api/services/brain/baseline.py

@@ -0,0 +1,230 @@
+# Brain v1 — Direction baseline resolver (sub-02 C2).
+# Priority chain: latest journal entry → latest project_status_update → latest
+# handoff (auto-handoff). Conflict detection across the three sources.
+# Never returns None — uses BaselineReference(source='none', ref=None) sentinel.
+#
+# Reads ONLY from L2 outputs (journal API) and read-only substrate. Drift rules
+# consume the precomputed baselines from CycleSnapshot.baselines.
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from core.api.db import acquire_db
+from core.api.models.brain import BaselineReference, DirectionSource, ScopeType
+from core.api.services.brain.journal import get_latest_entry
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_iso(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    try:
+        dt = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+async def _resolve_project_direction(
+    *, scope_type: ScopeType, scope_key: str, as_of: datetime
+) -> tuple[str | None, datetime | None]:
+    """Return (ref, last_updated_at) of the project_directions row for a slug.
+
+    Brain v1.2: this is the priority-1 source of baseline truth for project
+    scope when present. Falls through silently when the table is empty
+    (cold start before bootstrap rollout) or the project lacks a direction.
+    """
+    if scope_type != "project":
+        return (None, None)
+    try:
+        async with acquire_db() as db:
+            row = await (
+                await db.execute(
+                    "SELECT project_slug, last_updated_at FROM project_directions"
+                    " WHERE project_slug = ?",
+                    (scope_key,),
+                )
+            ).fetchone()
+    except Exception as exc:  # noqa: BLE001 — table may not exist on cold DB
+        logger.debug("baseline: project_directions lookup skipped (%s)", exc)
+        return (None, None)
+    if row is None:
+        return (None, None)
+    slug = row[0] if not hasattr(row, "keys") else row["project_slug"]
+    state_at = row[1] if not hasattr(row, "keys") else row["last_updated_at"]
+    return (f"project_directions:{slug}", _parse_iso(state_at))
+
+
+async def _resolve_status_update(
+    *, scope_type: ScopeType, scope_key: str, as_of: datetime, workspace_id: str
+) -> tuple[str | None, datetime | None]:
+    """Return (ref, state_at) of the latest project_status_update for the scope.
+
+    Restricted to project scope (status updates are project-only). For company
+    or program scope returns (None, None) — falls through to handoff.
+    """
+    if scope_type != "project":
+        return (None, None)
+    cutoff = as_of.astimezone(timezone.utc).isoformat()
+    try:
+        async with acquire_db() as db:
+            row = await (
+                await db.execute(
+                    "SELECT update_id, created_at FROM project_status_updates "
+                    "WHERE project = ? AND created_at <= ? "
+                    "AND COALESCE(derived, 0) = 0 "
+                    "ORDER BY created_at DESC LIMIT 1",
+                    (scope_key, cutoff),
+                )
+            ).fetchone()
+    except Exception as exc:  # noqa: BLE001 — table may not exist in test DB
+        logger.debug("baseline: status update lookup skipped (%s)", exc)
+        return (None, None)
+    if row is None:
+        return (None, None)
+    ref = row[0] if not hasattr(row, "keys") else row["update_id"]
+    state_at = row[1] if not hasattr(row, "keys") else row["created_at"]
+    return (f"project_status_update:{ref}", _parse_iso(state_at))
+
+
+async def _resolve_handoff(
+    *, scope_type: ScopeType, scope_key: str, as_of: datetime, workspace_id: str
+) -> tuple[str | None, datetime | None]:
+    """Return (ref, state_at) of the latest auto_handoff for the scope."""
+    cutoff = as_of.astimezone(timezone.utc).isoformat()
+    try:
+        async with acquire_db() as db:
+            row = await (
+                await db.execute(
+                    "SELECT handoff_id, created_at FROM handoffs "
+                    "WHERE project = ? AND created_at <= ? "
+                    "AND COALESCE(kind, '') IN ('auto_handoff','handoff') "
+                    "ORDER BY created_at DESC LIMIT 1",
+                    (scope_key,) if scope_type == "project" else (scope_key,),
+                )
+            ).fetchone()
+    except Exception as exc:  # noqa: BLE001 — table may not exist
+        logger.debug("baseline: handoff lookup skipped (%s)", exc)
+        return (None, None)
+    if row is None:
+        return (None, None)
+    ref = row[0] if not hasattr(row, "keys") else row["handoff_id"]
+    state_at = row[1] if not hasattr(row, "keys") else row["created_at"]
+    return (f"handoff:{ref}", _parse_iso(state_at))
+
+
+def _direction_marker(payload: Any) -> str | None:
+    if isinstance(payload, dict):
+        marker = payload.get("direction_marker") or payload.get("direction")
+        if isinstance(marker, str):
+            return marker.strip().lower() or None
+    return None
+
+
+async def resolve_baseline(
+    scope_type: ScopeType,
+    scope_key: str,
+    *,
+    cycle_key: str,
+    as_of: datetime,
+    workspace_id: str = "ws_default",
+    visible_projects: set[str] | None = None,
+) -> BaselineReference:
+    """Resolve the expected direction baseline for the scope.
+
+    Priority chain (sub-02 C2):
+      1. Latest Journal entry within cycle window.
+      2. Latest project status update within 7d (derived=False).
+      3. Latest handoff within 7d (auto_handoff or handoff kind).
+
+    Returns BaselineReference(source='none') sentinel when nothing matches.
+    Conflict detection compares direction markers across resolved sources.
+    """
+    # Visibility short-circuit: if caller can see only some projects and this
+    # one isn't visible, refuse to leak existence.
+    if (
+        scope_type == "project"
+        and visible_projects is not None
+        and scope_key not in visible_projects
+    ):
+        return BaselineReference(source="none", ref=None, confidence=0.7)
+
+    # Brain v1.2 (2026-05-18): project_directions becomes the priority-1
+    # source for project scope. Falls back to journal -> status -> handoff
+    # when no direction is present (bootstrap not yet applied).
+    direction_ref, direction_state_at = await _resolve_project_direction(
+        scope_type=scope_type, scope_key=scope_key, as_of=as_of
+    )
+
+    journal = await get_latest_entry(
+        scope_type, scope_key, before=cycle_key, workspace_id=workspace_id
+    )
+    journal_ref: str | None = None
+    journal_state_at: datetime | None = None
+    journal_marker: str | None = None
+    if journal is not None:
+        journal_ref = f"journal_entry:{journal.entry_id}"
+        journal_state_at = journal.published_at
+        journal_marker = _direction_marker(journal.body.model_dump())
+
+    status_ref, status_state_at = await _resolve_status_update(
+        scope_type=scope_type, scope_key=scope_key, as_of=as_of, workspace_id=workspace_id
+    )
+    handoff_ref, handoff_state_at = await _resolve_handoff(
+        scope_type=scope_type, scope_key=scope_key, as_of=as_of, workspace_id=workspace_id
+    )
+
+    chain: list[tuple[DirectionSource, str | None, datetime | None]] = [
+        ("doc", direction_ref, direction_state_at),
+        ("journal", journal_ref, journal_state_at),
+        ("project_status", status_ref, status_state_at),
+        ("handoff", handoff_ref, handoff_state_at),
+    ]
+    primary: tuple[DirectionSource, str | None, datetime | None] | None = None
+    secondary: list[tuple[DirectionSource, str | None, datetime | None]] = []
+    for entry in chain:
+        if entry[1]:
+            if primary is None:
+                primary = entry
+            else:
+                secondary.append(entry)
+    if primary is None:
+        return BaselineReference(source="none", ref=None, confidence=0.7)
+
+    secondary_refs = [s[1] for s in secondary if s[1]]
+    # Conflict: at least two sources present and direction markers disagree.
+    # Without direction_marker on status/handoff substrate we only flag conflict
+    # if journal_marker exists AND a secondary source disagrees explicitly.
+    conflict = False
+    if journal_marker and secondary_refs:
+        # Best-effort: load secondary direction markers from handoff_summary etc.
+        # In v1 we mark conflict if multiple secondaries exist (proxy for
+        # divergence pressure). Future v1.1 will compare typed direction tags.
+        conflict = len(secondary_refs) >= 2
+
+    source: DirectionSource = primary[0]
+    confidence_base = {
+        "doc": 1.0,            # project_directions = founder-declared
+        "journal": 1.0,
+        "project_status": 0.9,
+        "handoff": 0.8,
+    }.get(source, 0.5)
+    if conflict:
+        confidence_base = max(0.3, confidence_base - 0.1)
+
+    return BaselineReference(
+        source=source,
+        ref=primary[1],
+        state_at=primary[2],
+        confidence=confidence_base,
+        conflict=conflict,
+        secondary_refs=secondary_refs,
+    )
+
+
+__all__ = ["resolve_baseline"]

core/api/services/brain/capabilities.py

@@ -0,0 +1,75 @@
+# Brain v1 — Capabilities (sub-05 §3.1, OD-11).
+# Schema metadata for agent cold-start. Mirrors graph_capabilities precedent.
+# Returns the Literal members enforced at the Pydantic boundary so agents can
+# discover enums without hardcoding constants.
+from __future__ import annotations
+
+from typing import get_args
+
+from core.api.models.brain import (
+    BrainCapabilities,
+    ConfidenceTier,
+    DriftAxis,
+    EventType,
+    FindingApprovalState,
+    FindingType,
+    KnowledgeForm,
+    RunStatus,
+    RunTrigger,
+    ScopeType,
+    Severity,
+    SignalState,
+    SignalType,
+    SourceSystem,
+    SuggestedArtifact,
+)
+
+# Note: ApprovalState, OperationType, ClosureConditionKind are imported lazily
+# to keep this module a leaf (no cycle with models.brain).
+
+KNOWLEDGE_GLYPHS: dict[str, str] = {
+    "adr": "▣",
+    "spec": "▦",
+    "playbook": "⌘",
+    "tribal_memory": "✶",
+    "external_update": "↘",
+    "claimed_decision": "!",
+    "unknown": "?",
+}
+
+
+def get_capabilities() -> BrainCapabilities:
+    """Snapshot of every Literal enum exposed by the Brain v1 surface."""
+    from core.api.models.brain import (
+        ApprovalState,
+        ClosureConditionKind,
+        OperationType,
+    )
+
+    def _literal_members(tp: object) -> list[str]:
+        return [str(m) for m in get_args(tp)]
+
+    return BrainCapabilities(
+        schema_version=1,
+        event_types=_literal_members(EventType),
+        source_systems=_literal_members(SourceSystem),
+        signal_types=_literal_members(SignalType),
+        knowledge_forms=_literal_members(KnowledgeForm),
+        operation_types=_literal_members(OperationType),
+        finding_types=_literal_members(FindingType),
+        severities=_literal_members(Severity),
+        confidence_tiers=_literal_members(ConfidenceTier),
+        drift_axes=_literal_members(DriftAxis),
+        approval_states=_literal_members(ApprovalState),
+        finding_approval_states=_literal_members(FindingApprovalState),
+        signal_states=_literal_members(SignalState),
+        run_statuses=_literal_members(RunStatus),
+        run_triggers=_literal_members(RunTrigger),
+        scope_types=_literal_members(ScopeType),
+        suggested_artifacts=_literal_members(SuggestedArtifact),
+        closure_condition_kinds=_literal_members(ClosureConditionKind),
+        knowledge_glyphs=dict(KNOWLEDGE_GLYPHS),
+    )
+
+
+__all__ = ["KNOWLEDGE_GLYPHS", "get_capabilities"]