claude-smart 0.2.47 → 0.2.49

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/_agent_run.py

@@ -1,378 +1,72 @@
-"""Shared storage types and helpers for resumable extraction agent runs."""
+"""Shared storage types and helpers for resumable extraction agent runs.
+
+Residual holder for the ``_agent_run.py`` decomposition. The 18 shared
+non-class symbols live in the leaf ``agent_run/_models.py`` and are re-exported
+here so ``storage_base/__init__.py`` keeps importing them from ``._agent_run``
+byte-identically. ``AgentRunMixin`` survives as a thin COMPOSITE ABC:
+``AgentRunStoreABC`` supplies the agent-run lifecycle stubs,
+``PendingToolCallStoreABC`` supplies the pending-tool-call stubs,
+``RunToolDependencyStoreABC`` supplies the run-tool-dependency stubs, and only
+the public helper staticmethods stay inline here. All twenty-three agent-run
+methods now live in the three ``agent_run`` sub-mixins.
+"""
 
 from __future__ import annotations
 
-import hashlib
-import json
-import re
-import unicodedata
-from dataclasses import dataclass, field
-from datetime import datetime
-from enum import StrEnum
-from typing import Any
-
-from reflexio.models.api_schema.pending_tool_call_schema import PendingToolCallStatus
-
-_WHITESPACE_RE = re.compile(r"\s+")
-
-
-class AgentRunStatus(StrEnum):
-    RUNNING = "running"
-    AGENT_COMPLETED = "agent_completed"
-    FINALIZING = "finalizing"
-    FINALIZED = "finalized"
-    FINALIZED_PENDING_TOOL = "finalized_pending_tool"
-    RESUME_READY = "resume_ready"
-    RESUMING = "resuming"
-    FINALIZATION_FAILED = "finalization_failed"
-    FAILED = "failed"
-    EXPIRED = "expired"
-    CANCELLED = "cancelled"
-
-
-NOT_APPLICABLE_ANSWER = "User does not have information about this question."
-
-
-class RunToolDependencyKind(StrEnum):
-    FOLLOWUP = "followup"
-
-
-@dataclass(frozen=True)
-class AgentBinding:
-    """Logical run binding flattened into `_agent_runs` storage columns."""
-
-    org_id: str
-    extractor_kind: str
-    user_id: str | None
-    request_id: str
-    agent_version: str | None
-    source: str | None
-    source_interaction_ids: list[int] = field(default_factory=list)
-    window_start_interaction_id: int | None = None
-    window_end_interaction_id: int | None = None
-    extractor_config_hash: str | None = None
-
-
-@dataclass(frozen=True)
-class AgentRunRecord:
-    id: str
-    binding: AgentBinding
-    status: AgentRunStatus
-    generation_request_snapshot: dict[str, Any]
-    service_config_snapshot: dict[str, Any] | None = None
-    agent_context_snapshot: str | None = None
-    committed_output: dict[str, Any] | None = None
-    pending_tool_call_ids: list[str] = field(default_factory=list)
-    max_steps_remaining: int | None = None
-    resume_attempts: int = 0
-    finalization_attempts: int = 0
-    next_resume_at: datetime | None = None
-    claimed_by: str | None = None
-    claimed_at: datetime | None = None
-    agent_completed_at: datetime | None = None
-    finalized_at: datetime | None = None
-    created_at: datetime | None = None
-    updated_at: datetime | None = None
-    expires_at: datetime | None = None
-    last_error: str | None = None
-
-
-@dataclass(frozen=True)
-class PendingToolCallRecord:
-    id: str
-    org_id: str
-    scope: dict[str, Any]
-    scope_hash: str
-    tool_name: str
-    dedup_key: str
-    status: PendingToolCallStatus
-    question_text: str
-    args: dict[str, Any] = field(default_factory=dict)
-    tags: list[str] = field(default_factory=list)
-    user_id: str | None = None
-    answer_format: str | None = None
-    result: dict[str, Any] | None = None
-    embedding: list[float] | None = None
-    superseded_by: str | None = None
-    created_at: datetime | None = None
-    resolved_at: datetime | None = None
-    expires_at: datetime | None = None
-    cache_until: datetime | None = None
-    valid_until: datetime | None = None
-
-
-@dataclass(frozen=True)
-class RunToolDependencyRecord:
-    run_id: str
-    pending_tool_call_id: str
-    dependency_kind: RunToolDependencyKind = RunToolDependencyKind.FOLLOWUP
-    resolved_at: datetime | None = None
-    consumed_at: datetime | None = None
-    created_at: datetime | None = None
-
-
-@dataclass(frozen=True)
-class PendingToolCallUpsertResult:
-    pending_tool_call: PendingToolCallRecord
-    created: bool
-
-
-@dataclass(frozen=True)
-class PriorAnswerMatch:
-    pending_tool_call_id: str
-    status: PendingToolCallStatus
-    question_text: str
-    result: dict[str, Any] | None
-    valid_until: datetime | None
-    answer_format: str | None = None
-    created_at: datetime | None = None
-    resolved_at: datetime | None = None
-    expires_at: datetime | None = None
-    similarity: float | None = None
-
-
-def canonical_json(value: Any) -> str:
-    """Return deterministic compact JSON for storage hashes."""
-    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
-
-
-def build_scope_hash(scope: dict[str, Any]) -> str:
-    """Stable hash for a tool scope dictionary."""
-    return hashlib.sha256(canonical_json(scope).encode("utf-8")).hexdigest()
-
-
-def human_feedback_scope(org_id: str) -> dict[str, str]:
-    """Human feedback is always org-scoped, never user-scoped."""
-    return {"org_id": org_id, "scope_kind": "org"}
-
-
-def normalize_dedup_text(value: str | None) -> str:
-    """Normalize text before pending-tool-call dedup hashing."""
-    if value is None:
-        return ""
-    normalized = unicodedata.normalize("NFKC", value)
-    normalized = _WHITESPACE_RE.sub(" ", normalized.strip())
-    return normalized.casefold()
-
-
-def build_pending_tool_call_dedup_key(
-    *,
-    tool_name: str,
-    question_text: str,
-    answer_format: str | None = None,
-) -> str:
-    """Stable dedup hash for a normalized tool question."""
-    parts = (
-        normalize_dedup_text(tool_name),
-        normalize_dedup_text(question_text),
-        normalize_dedup_text(answer_format),
-    )
-    return hashlib.sha256("\n".join(parts).encode("utf-8")).hexdigest()
-
-
-def not_applicable_tool_result() -> dict[str, Any]:
-    return {"answer": NOT_APPLICABLE_ANSWER, "not_applicable": True}
-
-
-def is_not_applicable_tool_result(result: dict[str, Any] | None) -> bool:
-    return isinstance(result, dict) and result.get("not_applicable") is True
-
-
-def embedding_similarity(a: list[float] | None, b: list[float] | None) -> float | None:
-    """Cosine similarity for optional embedding vectors."""
-    if not a or not b or len(a) != len(b):
-        return None
-    dot = sum(x * y for x, y in zip(a, b, strict=True))
-    mag_a_sq = sum(x * x for x in a)
-    mag_b_sq = sum(y * y for y in b)
-    if mag_a_sq == 0.0 or mag_b_sq == 0.0:
-        return None
-    return dot / ((mag_a_sq**0.5) * (mag_b_sq**0.5))
-
-
-class AgentRunMixin:
+from .agent_run import (
+    AgentRunStoreABC,
+    PendingToolCallStoreABC,
+    RunToolDependencyStoreABC,
+)
+from .agent_run._models import (
+    NOT_APPLICABLE_ANSWER,
+    AgentBinding,
+    AgentRunRecord,
+    AgentRunStatus,
+    PendingToolCallRecord,
+    PendingToolCallStatus,
+    PendingToolCallUpsertResult,
+    PriorAnswerMatch,
+    RunToolDependencyKind,
+    RunToolDependencyRecord,
+    build_pending_tool_call_dedup_key,
+    build_scope_hash,
+    canonical_json,
+    embedding_similarity,
+    human_feedback_scope,
+    is_not_applicable_tool_result,
+    normalize_dedup_text,
+    not_applicable_tool_result,
+)
+
+__all__ = [
+    "NOT_APPLICABLE_ANSWER",
+    "AgentBinding",
+    "AgentRunMixin",
+    "AgentRunRecord",
+    "AgentRunStatus",
+    "PendingToolCallRecord",
+    "PendingToolCallStatus",
+    "PendingToolCallUpsertResult",
+    "PriorAnswerMatch",
+    "RunToolDependencyKind",
+    "RunToolDependencyRecord",
+    "build_pending_tool_call_dedup_key",
+    "build_scope_hash",
+    "canonical_json",
+    "embedding_similarity",
+    "human_feedback_scope",
+    "is_not_applicable_tool_result",
+    "normalize_dedup_text",
+    "not_applicable_tool_result",
+]
+
+
+class AgentRunMixin(
+    AgentRunStoreABC, PendingToolCallStoreABC, RunToolDependencyStoreABC
+):
     """Backend-neutral helpers shared by resumable extraction storage backends."""
 
     build_scope_hash = staticmethod(build_scope_hash)
     human_feedback_scope = staticmethod(human_feedback_scope)
     build_pending_tool_call_dedup_key = staticmethod(build_pending_tool_call_dedup_key)
-
-    def create_agent_run(self, record: AgentRunRecord) -> AgentRunRecord:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def get_agent_run(self, run_id: str) -> AgentRunRecord | None:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def update_agent_run_status(
-        self,
-        run_id: str,
-        status: AgentRunStatus,
-        *,
-        committed_output: dict[str, Any] | None = None,
-        pending_tool_call_ids: list[str] | None = None,
-        max_steps_remaining: int | None = None,
-        next_resume_at: datetime | None = None,
-        last_error: str | None = None,
-        increment_finalization_attempts: bool = False,
-        expected_statuses: tuple[AgentRunStatus, ...] | None = None,
-    ) -> AgentRunRecord | None:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def fail_running_agent_runs_for_request(
-        self,
-        *,
-        org_id: str,
-        extractor_kind: str,
-        user_id: str | None,
-        request_id: str,
-        last_error: str,
-    ) -> int:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def create_pending_tool_call(
-        self, record: PendingToolCallRecord
-    ) -> PendingToolCallRecord:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def create_or_attach_pending_tool_call(
-        self,
-        *,
-        record: PendingToolCallRecord,
-        dependency: RunToolDependencyRecord,
-        now: datetime | None = None,
-    ) -> PendingToolCallUpsertResult:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def get_pending_tool_call(self, call_id: str) -> PendingToolCallRecord | None:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def list_pending_tool_calls(
-        self,
-        *,
-        status: PendingToolCallStatus | None = None,
-        limit: int = 100,
-    ) -> list[PendingToolCallRecord]:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def cancel_pending_tool_call(
-        self,
-        call_id: str,
-        *,
-        cancelled_at: datetime | None = None,
-    ) -> PendingToolCallRecord | None:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def expire_pending_tool_calls(
-        self,
-        *,
-        now: datetime | None = None,
-        limit: int = 100,
-    ) -> int:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def find_active_pending_tool_call(
-        self,
-        *,
-        org_id: str,
-        scope_hash: str,
-        tool_name: str,
-        dedup_key: str,
-        now: datetime | None = None,
-    ) -> PendingToolCallRecord | None:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def search_prior_tool_calls(
-        self,
-        *,
-        org_id: str,
-        scope_hash: str,
-        tool_name: str,
-        query_embedding: list[float] | None = None,
-        now: datetime | None = None,
-        limit: int = 8,
-    ) -> list[PriorAnswerMatch]:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def attach_run_tool_dependency(
-        self, record: RunToolDependencyRecord
-    ) -> RunToolDependencyRecord:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def count_unresolved_followup_dependencies(
-        self,
-        *,
-        org_id: str,
-        extractor_kind: str,
-        tool_name: str,
-    ) -> int:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def list_run_tool_dependencies(self, run_id: str) -> list[RunToolDependencyRecord]:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def resolve_pending_tool_call(
-        self,
-        call_id: str,
-        *,
-        result: dict[str, Any],
-        resolved_at: datetime | None = None,
-        valid_for_seconds: int,
-    ) -> PendingToolCallRecord | None:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def update_resolved_pending_tool_call_result(
-        self,
-        call_id: str,
-        *,
-        result: dict[str, Any],
-        resolved_at: datetime | None = None,
-        valid_for_seconds: int,
-    ) -> PendingToolCallRecord | None:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def mark_pending_tool_call_not_applicable(
-        self,
-        call_id: str,
-        *,
-        resolved_at: datetime | None = None,
-        valid_for_seconds: int,
-    ) -> PendingToolCallRecord | None:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def claim_ready_agent_run(
-        self,
-        *,
-        org_id: str,
-        worker_id: str,
-        now: datetime | None = None,
-        claim_ttl_seconds: int = 600,
-    ) -> AgentRunRecord | None:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def claim_finalization_failed_agent_run(
-        self,
-        *,
-        org_id: str,
-        worker_id: str,
-        now: datetime | None = None,
-        claim_ttl_seconds: int = 600,
-    ) -> AgentRunRecord | None:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def list_resumable_work_org_ids(
-        self,
-        *,
-        now: datetime | None = None,
-        limit: int = 1000,
-    ) -> list[str]:
-        """Return distinct org_ids that have actionable resumable-extraction work.
-
-        Cross-org maintenance query (intentionally NOT scoped to ``self.org_id``):
-        the resume scheduler uses it to discover every org that has a run ready
-        to resume, a run awaiting finalization retry, or a pending tool call that
-        can be expired, so per-org workers can be driven for all of them.
-        """
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")
-
-    def consume_run_tool_dependencies(self, run_id: str) -> int:
-        raise NotImplementedError(f"{type(self).__name__} does not support agent runs")

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/_commit_scope.py

@@ -0,0 +1,9 @@
+from abc import ABC, abstractmethod
+from contextlib import AbstractContextManager
+
+
+class CommitScopeMixin(ABC):
+    @abstractmethod
+    def commit_scope(self) -> AbstractContextManager[None]:
+        """Atomic multi-write transaction; see Workstream A plan Task 1."""
+        raise NotImplementedError

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/_learning_jobs.py

@@ -0,0 +1,219 @@
+"""ABC, dataclass, and enum for the durable learning-job queue (Task 3)."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Literal
+
+# Upper bound of the done-row retention window.
+# Shared by all backends so the value cannot drift between implementations.
+# Err toward "not done" until we are sure a done row would have been GC'd.
+_ABSENCE_DONE_AFTER_SECONDS = 72 * 3600
+
+# Coverage-based status reported for a single request (§3.6). This is a
+# collapsed view of the raw job statuses (e.g. claimed -> processing,
+# reclaimable failed -> pending) and matches LearningStatusResponse.status.
+LearningStatus = Literal["pending", "processing", "done", "failed"]
+
+
+class LearningJobStatus(StrEnum):
+    PENDING = "pending"
+    CLAIMED = "claimed"
+    DONE = "done"
+    FAILED = "failed"
+    DEAD = "dead"
+
+
+@dataclass(frozen=True)
+class LearningJob:
+    job_id: str
+    org_id: str
+    user_id: str
+    job_type: str
+    latest_request_id: str | None
+    status: str
+    attempts: int
+    claim_token: str | None
+    covers_through: (
+        float | None
+    )  # epoch seconds (converted from stored ISO/timestamptz)
+    force_extraction: bool = False
+    skip_aggregation: bool = False
+    max_attempts: int = 3
+
+
+class LearningJobStoreABC(ABC):
+    """Abstract interface for durable learning-job queue operations.
+
+    All methods are scoped to the storage instance's own org (``self.org_id``).
+    ``enqueue_learning_job`` and ``complete_learning_job`` are safe to call
+    inside a ``commit_scope`` — they issue plain SQL on the scope's connection
+    without owning a separate BEGIN/COMMIT.
+    """
+
+    @abstractmethod
+    def enqueue_learning_job(
+        self,
+        *,
+        org_id: str,
+        user_id: str,
+        request_id: str,
+        covers_through: float,
+        job_type: str = "learning",
+        force_extraction: bool = False,
+        skip_aggregation: bool = False,
+    ) -> str:
+        """Coalescing upsert into the learning_jobs queue.
+
+        If a pending job for ``(org_id, user_id, job_type)`` already exists,
+        update its ``latest_request_id`` and keep the max ``covers_through``;
+        otherwise insert a new ``pending`` row.  Returns the ``job_id`` of the
+        pending row (existing or newly inserted).
+
+        Safe to call inside a ``commit_scope`` — no own BEGIN/COMMIT issued.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def claim_learning_jobs(
+        self,
+        *,
+        claimed_by: str,
+        limit: int,
+        lease_seconds: int,
+    ) -> list[LearningJob]:
+        """Atomically claim up to ``limit`` of this org's claimable jobs.
+
+        A job is claimable when it is ``pending``, ``failed`` (reclaimable —
+        attempts < max_attempts), OR (``claimed`` AND
+        ``claim_expires_at < now``).  Each claimed job receives a fresh
+        ``claim_token``, ``claimed_by``, and ``claim_expires_at``.
+
+        Postgres/Supabase: uses ``FOR UPDATE SKIP LOCKED`` via the
+        ``claim_learning_jobs`` SQL function.  SQLite: ``BEGIN IMMEDIATE``.
+        The claim predicate uses the DB's ``now()`` to avoid app/DB clock skew.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def heartbeat_learning_job(
+        self,
+        *,
+        job_id: str,
+        claim_token: str,
+        lease_seconds: int,
+    ) -> bool:
+        """Extend the lease on a claimed job.
+
+        Updates ``claim_expires_at = now + lease_seconds`` only when
+        ``claim_token`` matches and status is still ``claimed``.
+
+        Returns:
+            True if the lease was extended (rowcount == 1), False if the token
+            was superseded or the job is no longer claimed.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def complete_learning_job(
+        self,
+        *,
+        job_id: str,
+        claim_token: str,
+    ) -> int:
+        """Fenced transition to ``done``.
+
+        Executes::
+
+            UPDATE learning_jobs
+               SET status='done', updated_at=now()
+             WHERE job_id=:job_id AND claim_token=:claim_token AND status='claimed'
+
+        Returns:
+            rowcount — 0 if the token was superseded or the job is already
+            done/dead/failed; 1 on success.  Callers MUST raise on 0 to roll
+            back the enclosing ``commit_scope``.
+
+        Safe to call inside a ``commit_scope`` — no own BEGIN/COMMIT issued.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def fail_learning_job(
+        self,
+        *,
+        job_id: str,
+        claim_token: str,
+        dead: bool,
+    ) -> None:
+        """Fenced fail/dead transition — sets status, does NOT increment attempts.
+
+        Fenced on ``claim_token`` and ``status='claimed'``.  Sets
+        ``status='dead'`` when ``dead=True``, else ``status='failed'`` (and
+        clears ``claim_token``/``claim_expires_at`` so the job is reclaimable).
+
+        ``attempts`` is intentionally NOT incremented here.  It is incremented
+        once per delivery attempt exclusively by ``claim_learning_jobs``; the
+        worker's dead-gate (``job.attempts >= max_attempts``) depends on that
+        single-increment-per-claim invariant.  Incrementing here would
+        double-count and misfire the dead transition.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def list_org_ids_with_pending_learning_jobs(self) -> list[str]:
+        """Return distinct org_ids that have actionable learning jobs.
+
+        Cross-org discovery query for the :class:`DurableLearningScheduler`:
+        surfaces every org with at least one job that is ``pending``, ``failed``
+        (reclaimable), or ``claimed`` with an expired lease (a stolen/abandoned
+        claim). Terminal ``done``/``dead`` rows and live claims are excluded.
+
+        Mirrors ``list_resumable_work_org_ids``: NOT scoped to ``self.org_id`` —
+        on the shared global table (Postgres ``public.learning_jobs``, or a
+        SQLite DB shared across orgs) it returns every org with work in one
+        query so the scheduler need not enumerate all orgs.
+
+        Returns:
+            list[str]: Distinct org_ids with actionable work, ordered ascending.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_learning_status_for_request(
+        self,
+        *,
+        user_id: str,
+        request_created_at: float,
+    ) -> LearningStatus:
+        """Coverage-based status for a single request (§3.6 rule).
+
+        Returns one of ``"done" | "processing" | "pending" | "failed"``.
+
+        Coverage rule (evaluated in priority order):
+
+        1. Any ``done`` job with ``covers_through >= request_created_at``
+           → ``"done"`` (correct even for zero-yield windows).
+        2. Any ``claimed`` job (any ``covers_through``)
+           → ``"processing"``.
+        3. Any ``pending`` job for this user
+           → ``"pending"``.
+        4. Any ``failed`` (reclaimable) job
+           → ``"pending"``.
+        5. Any ``dead`` job with ``covers_through >= request_created_at``
+           → ``"failed"``.
+        6. No rows AND ``now - request_created_at >= 72 h`` (retention window)
+           → ``"done"`` (done row would have been GC'd by now).
+        7. No rows AND request is recent
+           → ``"pending"`` (err toward not-done until retention window passes).
+        """
+        raise NotImplementedError
+
+
+__all__ = [
+    "_ABSENCE_DONE_AFTER_SECONDS",
+    "LearningJob",
+    "LearningJobStatus",
+    "LearningStatus",
+    "LearningJobStoreABC",
+]

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/_share_links.py

@@ -91,3 +91,23 @@ class ShareLinkMixin:
             int: Number of links deleted.
         """
         raise NotImplementedError
+
+    @abstractmethod
+    def delete_expired_share_links(
+        self, *, now: int, grace_seconds: int, limit: int = 1000
+    ) -> int:
+        """Physically delete share links whose expires_at < now - grace_seconds.
+
+        Rows where expires_at IS NULL (never expire) are always preserved.
+
+        Args:
+            now (int): Current Unix epoch timestamp.
+            grace_seconds (int): Additional grace window; only rows with
+                expires_at < (now - grace_seconds) are deleted.
+            limit (int): Maximum number of rows to delete in one call.
+                Rows are processed in expires_at ASC order (oldest first).
+
+        Returns:
+            int: Number of rows physically deleted.
+        """
+        raise NotImplementedError