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

server/services/secret_encryption.py

@@ -0,0 +1,97 @@
+"""Fernet-based at-rest encryption for sensitive string columns (cleanup follow-up PR3).
+
+Used by ``server.domain.encrypted_types.EncryptedString`` to make
+``Webhook.secret`` (and future sensitive columns) opaque in DB dumps —
+the column at rest is a Fernet token; the application decrypts on read.
+
+Key resolution
+--------------
+The Fernet key (32-byte urlsafe-base64) is loaded from
+``MAP_WEBHOOK_SECRET_ENCRYPTION_KEY``. If unset, ``get_fernet()`` raises
+``SecretEncryptionKeyMissing`` — we deliberately do NOT silently derive a
+key from another secret (e.g. ``MAP_ADMIN_TOKEN``), because that would
+make "key rotation by env var change" ambiguous.
+
+Migration coupling
+------------------
+Alembic migration 037 calls :func:`encrypt_value` directly to backfill
+existing plaintext ``Webhook.secret`` rows. The migration loads the same
+env var via ``server.config.get_settings`` so prod / dev / test share one
+key path.
+
+Test override
+-------------
+Tests can call :func:`set_key_for_tests` to inject a deterministic key
+without touching env vars / settings cache.
+"""
+
+from __future__ import annotations
+
+import threading
+
+from cryptography.fernet import Fernet
+
+from server.config import get_settings
+
+_TEST_KEY_LOCK = threading.Lock()
+_TEST_KEY: bytes | None = None
+
+
+class SecretEncryptionKeyMissing(RuntimeError):
+    """Raised when ``MAP_WEBHOOK_SECRET_ENCRYPTION_KEY`` is unset and no
+    test key has been injected via :func:`set_key_for_tests`.
+
+    This is intentional: we never silently fall back to deriving a key
+    from another secret, because that would make key rotation
+    ambiguous.
+    """
+
+
+def _load_key_from_settings() -> bytes:
+    raw = get_settings().webhook_secret_encryption_key
+    if not raw:
+        raise SecretEncryptionKeyMissing(
+            "MAP_WEBHOOK_SECRET_ENCRYPTION_KEY is not set. "
+            "Generate one with `python -c 'from cryptography.fernet import "
+            "Fernet; print(Fernet.generate_key().decode())'` and add it "
+            "to your environment / .env file."
+        )
+    return raw.encode("utf-8")
+
+
+def get_fernet() -> Fernet:
+    """Return a :class:`cryptography.fernet.Fernet` keyed for the current process."""
+    if _TEST_KEY is not None:
+        return Fernet(_TEST_KEY)
+    return Fernet(_load_key_from_settings())
+
+
+def set_key_for_tests(key: bytes | None) -> None:
+    """Inject a deterministic key for the current test. Pass ``None`` to clear.
+
+    Only intended for unit tests; production code paths should resolve the
+    key via env var.
+    """
+    with _TEST_KEY_LOCK:
+        global _TEST_KEY
+        _TEST_KEY = key
+
+
+def encrypt_value(plaintext: str) -> str:
+    """Encrypt ``plaintext`` and return the Fernet token as a UTF-8 string."""
+    if plaintext is None:
+        raise ValueError("encrypt_value requires a non-None plaintext")
+    return get_fernet().encrypt(plaintext.encode("utf-8")).decode("utf-8")
+
+
+def decrypt_value(ciphertext: str) -> str:
+    """Decrypt a Fernet token back to its plaintext UTF-8 string.
+
+    Raises ``InvalidToken`` if the ciphertext was encrypted with a different
+    key, or if it isn't a valid Fernet token. Callers (TypeDecorator,
+    migration) must NOT swallow this — silent decryption failures would
+    send an empty / garbage HMAC secret to webhook receivers.
+    """
+    if ciphertext is None:
+        raise ValueError("decrypt_value requires a non-None ciphertext")
+    return get_fernet().decrypt(ciphertext.encode("utf-8")).decode("utf-8")

server/services/similarity_service.py

@@ -0,0 +1,119 @@
+"""b72d0542 I1.b(2)(b) — Log content similarity soft validator.
+
+Wraps the plan-(b) "embedding cosine + threshold 0.7" check with a
+structured warning shape and the soft-validation invariant
+(``valid`` is always True so ``experiment log`` is never blocked).
+
+The real cosine implementation lands in plan-(f) (``sentence-transformers
+/all-MiniLM-L6-v2``); for now this stub fires a deterministic
+placeholder similarity so the (e) ``--force`` + audit plumbing can be
+exercised end-to-end:
+
+* identical body to the previous log on the same experiment →
+  ``score=1.0`` → ``HIGH_CONTENT_SIMILARITY`` warning
+* otherwise → ``score=0.0`` → no warning
+
+Threshold, model id, and warning code are exported as constants so the
+audit/CLI layers read them from a single source of truth. Once (f)
+ships, ``_score_against_last_log`` is swapped to the real embedding
+without touching callers.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Literal
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from server.domain.models import ExperimentLog
+
+SIMILARITY_THRESHOLD: float = 0.7
+SIMILARITY_MODEL_ID: str = "placeholder:jaccard-v0"
+
+SimilarityWarningCode = Literal["HIGH_CONTENT_SIMILARITY"]
+
+
+@dataclass(frozen=True)
+class SimilarityWarning:
+    code: SimilarityWarningCode
+    score: float
+    threshold: float
+    ref_log_id: uuid.UUID
+    model: str
+
+
+@dataclass(frozen=True)
+class SimilarityValidationResult:
+    warnings: list[SimilarityWarning] = field(default_factory=list)
+    threshold: float = SIMILARITY_THRESHOLD
+    model: str = SIMILARITY_MODEL_ID
+
+    @property
+    def valid(self) -> bool:
+        """Soft validation invariant: always True (b72d0542 I1.b(2)).
+
+        Mirrors :class:`evidence_service.EvidenceValidationResult.valid`.
+        Host is expected to follow up with another log or pass
+        ``force_skip_similarity=True`` to acknowledge the warning.
+        """
+        return True
+
+
+def _score_against_last_log(
+    db: Session,
+    *,
+    experiment_id: uuid.UUID,
+    content_md: str,
+) -> tuple[float, uuid.UUID | None]:
+    """Return ``(score, ref_log_id)`` against the most recent prior log.
+
+    Placeholder similarity (b72d0542 I1.b(2) pre-(f)):
+        score = 1.0 if previous log body is byte-identical, else 0.0
+        ref_log_id = previous log id (always set when prior log exists)
+
+    Real implementation in plan-(f) uses
+    ``sentence-transformers/all-MiniLM-L6-v2`` cosine similarity.
+    """
+    stmt = (
+        select(ExperimentLog)
+        .where(ExperimentLog.experiment_id == experiment_id)
+        .order_by(ExperimentLog.log_index.desc())
+        .limit(1)
+    )
+    last = db.scalar(stmt)
+    if last is None:
+        return 0.0, None
+    if last.content_md == content_md:
+        return 1.0, last.id
+    return 0.0, last.id
+
+
+def validate_log_similarity(
+    db: Session,
+    *,
+    experiment_id: uuid.UUID,
+    content_md: str,
+) -> SimilarityValidationResult:
+    """Compute similarity against the most-recent prior log.
+
+    Soft validation — returns warnings but never raises. The log create
+    path always succeeds; the warning is purely advisory.
+    """
+    score, ref_log_id = _score_against_last_log(
+        db, experiment_id=experiment_id, content_md=content_md
+    )
+    warnings: list[SimilarityWarning] = []
+    if ref_log_id is not None and score >= SIMILARITY_THRESHOLD:
+        warnings.append(
+            SimilarityWarning(
+                code="HIGH_CONTENT_SIMILARITY",
+                score=score,
+                threshold=SIMILARITY_THRESHOLD,
+                ref_log_id=ref_log_id,
+                model=SIMILARITY_MODEL_ID,
+            )
+        )
+    return SimilarityValidationResult(warnings=warnings)

server/services/sse_event_schemas.py

@@ -0,0 +1,17 @@
+"""SSE wire-format schemas (transport layer)."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+# Fields allowed only on the SSE transport envelope (not domain models).
+SSE_TRANSPORT_ONLY_FIELDS = frozenset({"type"})
+
+# Published by notification_service._emit_created via notification_stream.publish.
+NOTIFICATION_CREATED_SSE_FIELDS = frozenset({"type", "event", "notification_id"})
+
+
+class NotificationCreatedSseEvent(TypedDict):
+    type: str
+    event: str
+    notification_id: str

server/services/status_service.py

@@ -0,0 +1,68 @@
+import uuid
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from server.domain.models import Experiment, ExperimentPhase
+from server.domain.schemas import ExperimentSummaryRead, GlobalStatusRead
+from server.services.project_service import build_projects_status, get_project, list_projects
+
+
+def get_global_status(db: Session, *, project_id: uuid.UUID | None = None) -> GlobalStatusRead:
+    if project_id is not None:
+        project = get_project(db, project_id)
+        project_status = build_projects_status(db, [project])[0]
+        counts_stmt = (
+            select(Experiment.phase, func.count())
+            .where(
+                Experiment.project_id == project_id,
+                Experiment.deleted_at.is_(None),
+                Experiment.archived_at.is_(None),
+            )
+            .group_by(Experiment.phase)
+        )
+        counts = {phase.value: count for phase, count in db.execute(counts_stmt)}
+        for phase in ExperimentPhase:
+            counts.setdefault(phase.value, 0)
+        recent_stmt = (
+            select(Experiment)
+            .where(
+                Experiment.project_id == project_id,
+                Experiment.deleted_at.is_(None),
+                Experiment.archived_at.is_(None),
+            )
+            .order_by(Experiment.updated_at.desc())
+            .limit(10)
+        )
+        recent = [ExperimentSummaryRead.model_validate(e) for e in db.scalars(recent_stmt)]
+        return GlobalStatusRead(
+            total_experiments_by_phase=counts,
+            projects=[project_status],
+            recent_experiments=recent,
+        )
+
+    projects = list_projects(db)
+    project_statuses = build_projects_status(db, projects)
+
+    counts_stmt = (
+        select(Experiment.phase, func.count())
+        .where(Experiment.deleted_at.is_(None), Experiment.archived_at.is_(None))
+        .group_by(Experiment.phase)
+    )
+    counts = {phase.value: count for phase, count in db.execute(counts_stmt)}
+    for phase in ExperimentPhase:
+        counts.setdefault(phase.value, 0)
+
+    recent_stmt = (
+        select(Experiment)
+        .where(Experiment.deleted_at.is_(None), Experiment.archived_at.is_(None))
+        .order_by(Experiment.updated_at.desc())
+        .limit(10)
+    )
+    recent = [ExperimentSummaryRead.model_validate(e) for e in db.scalars(recent_stmt)]
+
+    return GlobalStatusRead(
+        total_experiments_by_phase=counts,
+        projects=project_statuses,
+        recent_experiments=recent,
+    )

server/services/template_service.py

@@ -0,0 +1,134 @@
+"""b72d0542 I1.a — Result submission 4-段 template soft validator.
+
+Wraps :mod:`map_client.result_template` with structured warnings and
+the soft-validation invariant (``valid`` is always True so the
+``experiment complete`` call is never blocked).
+
+Used by the complete path (planned I1.b: wire into ``complete_experiment``
+endpoint and surface via CLI). Soft warnings:
+
+* ``MISSING_TEMPLATE_SECTION`` — one of the 4 required H2 sections is
+  absent from the result submission content.
+* ``NO_LINK_IN_LOG_SECTION`` — ``## 实施 log`` section is present but
+  contains no ``[text](url)`` markdown link.
+* ``MALFORMED_MARKDOWN_LINK`` — ``## 实施 log`` section has a
+  link-like fragment that is unbalanced (``[text`` without ``]`` or
+  ``(url`` without ``)``).
+
+The warnings are returned as a list of frozen dataclasses; the API/SDK
+wrappers (planned I1.b) convert these into Pydantic schemas with the
+same shape as the evidence warnings (8ac93d4e).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from map_client.result_template import (
+    REQUIRED_SECTION_NAMES,
+    extract_malformed_link_fragment,
+    parse_result_submission,
+)
+
+TemplateWarningCode = Literal[
+    "MISSING_TEMPLATE_SECTION",
+    "NO_LINK_IN_LOG_SECTION",
+    "MALFORMED_MARKDOWN_LINK",
+]
+
+
+@dataclass(frozen=True)
+class TemplateWarning:
+    code: TemplateWarningCode
+    section: str | None = None
+    detail: str | None = None
+
+
+@dataclass(frozen=True)
+class TemplateValidationResult:
+    warnings: list[TemplateWarning] = field(default_factory=list)
+    sections_present: tuple[str, ...] = ()
+    log_link_count: int = 0
+
+    @property
+    def valid(self) -> bool:
+        """Soft validation invariant: always True.
+
+        Mirrors :class:`evidence_service.EvidenceValidationResult.valid`.
+        Host is expected to follow up with another log if warnings
+        indicate missing sections; the validator never blocks the save.
+        """
+        return True
+
+
+def validate_result_submission_template(
+    content_md: str | None,
+) -> TemplateValidationResult:
+    """Validate that ``content_md`` follows the 4-段 template contract.
+
+    Soft validation — returns warnings but never raises. The complete
+    path always succeeds; the validator is purely advisory.
+
+    Acceptance cases (from plan acceptance (a)):
+
+    1. **完整 4 段**: all 4 sections present, ``## 实施 log`` has at
+       least one well-formed ``[text](url)`` → ``warnings=[]``.
+    2. **缺 summary**: any of the 4 sections missing →
+       ``MISSING_TEMPLATE_SECTION`` per missing section.
+    3. **缺 acceptance 清单**: same as case 2 — coverage by
+       ``MISSING_TEMPLATE_SECTION``.
+    4. **markdown link 格式错误**: ``## 实施 log`` present but contains
+       an unbalanced ``[text`` or ``(url`` fragment →
+       ``MALFORMED_MARKDOWN_LINK`` with the offending fragment in
+       ``detail``. A section with no link at all produces
+       ``NO_LINK_IN_LOG_SECTION`` instead (different code).
+    """
+    if not content_md:
+        # Empty body → all 4 sections missing.
+        warnings = [
+            TemplateWarning(code="MISSING_TEMPLATE_SECTION", section=name)
+            for name in REQUIRED_SECTION_NAMES
+        ]
+        return TemplateValidationResult(warnings=warnings, sections_present=())
+
+    parsed = parse_result_submission(content_md)
+
+    # Sections present in canonical order.
+    present_in_order = tuple(
+        name for name in REQUIRED_SECTION_NAMES if name in parsed.present
+    )
+
+    warnings: list[TemplateWarning] = []
+
+    # 1. Missing-section warnings.
+    for name in REQUIRED_SECTION_NAMES:
+        if not parsed.present[name]:
+            warnings.append(TemplateWarning(code="MISSING_TEMPLATE_SECTION", section=name))
+
+    # 2 & 3. Log-section link warnings (only meaningful when log section exists).
+    if parsed.log_present:
+        if not parsed.log_links:
+            warnings.append(
+                TemplateWarning(code="NO_LINK_IN_LOG_SECTION", section="实施 log")
+            )
+        else:
+            # Detect malformed fragments inside the log section body.
+            from map_client.result_template import _slice_section_body
+
+            log_body = _slice_section_body(content_md, "实施 log") or ""
+            fragment = extract_malformed_link_fragment(log_body)
+            if fragment is not None:
+                warnings.append(
+                    TemplateWarning(
+                        code="MALFORMED_MARKDOWN_LINK",
+                        section="实施 log",
+                        detail=fragment,
+                    )
+                )
+
+    return TemplateValidationResult(
+        warnings=warnings,
+        sections_present=present_in_order,
+        log_link_count=len(parsed.log_links),
+    )

server/services/text_utils.py

@@ -0,0 +1,19 @@
+"""Shared text helpers for service-layer excerpts.
+
+Centralises the 200-char excerpt previously duplicated as
+``mention_service._excerpt``, ``topic_service._topic_comment_excerpt`` and
+``todo_service._excerpt``. Co-locating it here also breaks the
+``todo_service ↔ topic_work_item_service`` import cycle: ``topic_work_item_service``
+used to import these helpers from ``todo_service``, forcing ``todo_service`` to
+lazily import ``topic_work_item_service``. The helpers now live in this
+dependency-free module.
+"""
+
+_EXCERPT_LEN = 200
+
+
+def excerpt(body: str, *, limit: int = _EXCERPT_LEN) -> str:
+    text = body.strip().replace("\n", " ")
+    if len(text) <= limit:
+        return text
+    return text[: limit - 1] + "…"

server/services/thread_activity.py

@@ -0,0 +1,180 @@
+"""Thread / container activity helpers (T3 D3 single module)."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Protocol
+
+from sqlalchemy import ColumnElement, select
+from sqlalchemy.orm import Session
+
+from server.domain.models import Comment, Mention, MentionSourceType, Topic, TopicComment
+
+
+def topic_comment_sort_key(comment: TopicComment) -> tuple:
+    """Canonical per-topic total order: wall clock, then seq, then id."""
+    return (comment.created_at, comment.comment_seq, comment.id)
+
+
+def topic_comment_order_clauses() -> tuple[ColumnElement[bool], ColumnElement[bool], ColumnElement[bool]]:
+    """SQLAlchemy ORDER BY for topic comments (ascending)."""
+    return (
+        TopicComment.created_at.asc(),
+        TopicComment.comment_seq.asc(),
+        TopicComment.id.asc(),
+    )
+
+
+def topic_comment_order_clauses_desc() -> tuple[ColumnElement[bool], ColumnElement[bool], ColumnElement[bool]]:
+    """SQLAlchemy ORDER BY for topic comments (descending / latest first)."""
+    return (
+        TopicComment.created_at.desc(),
+        TopicComment.comment_seq.desc(),
+        TopicComment.id.desc(),
+    )
+
+
+class _CommentLike(Protocol):
+    id: uuid.UUID
+    author_agent_id: uuid.UUID
+    parent_comment_id: uuid.UUID | None
+    created_at: object
+
+
+def thread_root_id(
+    comment_id: uuid.UUID,
+    by_id: dict[uuid.UUID, TopicComment],
+) -> uuid.UUID:
+    """Walk parent_comment_id to the top-level comment; that id is the thread root."""
+    current = by_id[comment_id]
+    while current.parent_comment_id is not None:
+        current = by_id[current.parent_comment_id]
+    return current.id
+
+
+def host_replied_after(
+    comment: TopicComment,
+    host_comment_ids: set[uuid.UUID],
+    by_id: dict[uuid.UUID, TopicComment],
+    *,
+    comment_order: list[uuid.UUID] | None = None,
+) -> bool:
+    """True when the host posted in the same thread after ``comment``."""
+    root = thread_root_id(comment.id, by_id)
+    if comment_order is None:
+        comment_order = sorted(by_id.keys(), key=lambda cid: topic_comment_sort_key(by_id[cid]))
+    try:
+        comment_pos = comment_order.index(comment.id)
+    except ValueError:
+        return False
+    for cid in host_comment_ids:
+        if thread_root_id(cid, by_id) != root:
+            continue
+        try:
+            host_pos = comment_order.index(cid)
+        except ValueError:
+            continue
+        if host_pos > comment_pos:
+            return True
+    return False
+
+
+def _is_reply_in_thread_to(
+    comment: TopicComment | Comment,
+    source: TopicComment | Comment,
+    by_id: dict[uuid.UUID, TopicComment | Comment],
+) -> bool:
+    cur: TopicComment | Comment | None = comment
+    while cur is not None and cur.parent_comment_id is not None:
+        if cur.parent_comment_id == source.id:
+            return True
+        cur = by_id.get(cur.parent_comment_id)
+    return False
+
+
+def comment_after(
+    db: Session,
+    *,
+    mention: Mention,
+    agent_id: uuid.UUID,
+) -> bool:
+    """True when ``agent_id`` posted in the same container after the mention source."""
+    if mention.source_type == MentionSourceType.topic and mention.topic_id is not None:
+        topic = db.get(Topic, mention.topic_id)
+        if topic is None:
+            return False
+        return (
+            db.scalar(
+                select(TopicComment.id)
+                .where(
+                    TopicComment.topic_id == mention.topic_id,
+                    TopicComment.author_agent_id == agent_id,
+                    TopicComment.created_at >= topic.created_at,
+                )
+                .order_by(*topic_comment_order_clauses())
+                .limit(1)
+            )
+            is not None
+        )
+
+    if mention.source_type == MentionSourceType.topic_comment and mention.topic_id is not None:
+        comments = list(
+            db.scalars(
+                select(TopicComment)
+                .where(TopicComment.topic_id == mention.topic_id)
+                .order_by(*topic_comment_order_clauses())
+            )
+        )
+    elif (
+        mention.source_type == MentionSourceType.experiment_comment
+        and mention.experiment_id is not None
+    ):
+        comments = list(
+            db.scalars(
+                select(Comment)
+                .where(Comment.experiment_id == mention.experiment_id)
+                .order_by(Comment.created_at.asc(), Comment.id.asc())
+            )
+        )
+    else:
+        return False
+
+    by_id = {comment.id: comment for comment in comments}
+    source = by_id.get(mention.source_id)
+    if source is None:
+        return False
+
+    for comment in comments:
+        if comment.author_agent_id != agent_id:
+            continue
+        if comment.id == mention.source_id:
+            continue
+        from server.services import topic_ack_service
+
+        if topic_ack_service._ack_kind(getattr(comment, "body", "") or "") is not None:
+            continue
+        if comment.created_at > source.created_at:
+            return True
+        if comment.created_at < source.created_at:
+            continue
+        if _is_reply_in_thread_to(comment, source, by_id):
+            return True
+        source_seq = getattr(source, "comment_seq", None)
+        comment_seq = getattr(comment, "comment_seq", None)
+        if source_seq is not None and comment_seq is not None:
+            if comment_seq > source_seq:
+                return True
+            continue
+        if comment.id > source.id:
+            return True
+    return False
+
+
+def replied_after(
+    db: Session,
+    *,
+    mention: Mention,
+    agent_id: uuid.UUID,
+) -> bool:
+    """Alias for ``comment_after`` (plan naming)."""
+    return comment_after(db, mention=mention, agent_id=agent_id)