claude-smart 0.2.42 → 0.2.44

package/plugin/vendor/reflexio/reflexio/server/services/extraction/invariants.py

@@ -0,0 +1,303 @@
+"""Plan-level invariants for the agentic-v2 extraction pipeline.
+
+Invariants are pure functions over ``ExtractionCtx``. Hard violations drop
+offending ops from the commit; soft violations are logged and applied.
+See spec §6 for the full catalog and severity policy.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from reflexio.server.services.extraction.plan import (
+    CommitResult,
+    CreateUserPlaybookOp,
+    CreateUserProfileOp,
+    DeleteUserPlaybookOp,
+    DeleteUserProfileOp,
+    ExtractionCtx,
+    Violation,
+)
+
+logger = logging.getLogger(__name__)
+
+PLAN_SIZE_CAP = 30
+
+
+# --- Hard invariants ---
+
+
+def inv_A_search_before_create(ctx: ExtractionCtx) -> list[Violation]:  # noqa: N802
+    """Every CreateOp must be preceded by ≥1 search_* call this run."""
+    create_indices = [
+        i
+        for i, op in enumerate(ctx.plan)
+        if isinstance(op, (CreateUserProfileOp, CreateUserPlaybookOp))
+    ]
+    if create_indices and ctx.search_count == 0:
+        return [
+            Violation(
+                code="A",
+                severity="hard",
+                affected_op_indices=create_indices,
+                msg="Plan has create ops but no search was performed this run",
+            )
+        ]
+    return []
+
+
+def inv_B_delete_known_id(ctx: ExtractionCtx) -> list[Violation]:  # noqa: N802
+    """Every DeleteOp(id) must reference an id in ctx.known_ids.
+
+    known_ids is populated by search/get/create tool handlers — so deletes
+    targeting hallucinated ids (agent never saw them) are rejected.
+    """
+    violations: list[Violation] = []
+    for i, op in enumerate(ctx.plan):
+        if (
+            isinstance(op, (DeleteUserProfileOp, DeleteUserPlaybookOp))
+            and op.id not in ctx.known_ids
+        ):
+            violations.append(
+                Violation(
+                    code="B",
+                    severity="hard",
+                    affected_op_indices=[i],
+                    msg=f"Delete of unknown id {op.id!r}",
+                )
+            )
+    return violations
+
+
+def inv_D_plan_size_cap(ctx: ExtractionCtx) -> list[Violation]:  # noqa: N802
+    """Plan cannot exceed PLAN_SIZE_CAP ops — guards runaway loops."""
+    if len(ctx.plan) > PLAN_SIZE_CAP:
+        overflow = list(range(PLAN_SIZE_CAP, len(ctx.plan)))
+        return [
+            Violation(
+                code="D",
+                severity="hard",
+                affected_op_indices=overflow,
+                msg=f"Plan size {len(ctx.plan)} exceeds cap {PLAN_SIZE_CAP}",
+            )
+        ]
+    return []
+
+
+def inv_F_no_duplicate_deletes(ctx: ExtractionCtx) -> list[Violation]:  # noqa: N802
+    """Same id cannot be deleted twice in one plan."""
+    seen: set[str] = set()
+    violations: list[Violation] = []
+    for i, op in enumerate(ctx.plan):
+        if isinstance(op, (DeleteUserProfileOp, DeleteUserPlaybookOp)):
+            if op.id in seen:
+                violations.append(
+                    Violation(
+                        code="F",
+                        severity="hard",
+                        affected_op_indices=[i],
+                        msg=f"Duplicate delete of id {op.id!r}",
+                    )
+                )
+            else:
+                seen.add(op.id)
+    return violations
+
+
+def inv_J_scope_match(_ctx: ExtractionCtx) -> list[Violation]:  # noqa: N802
+    """User_id scope is primarily enforced at the storage layer (handlers inject
+    ctx.user_id). This invariant is a placeholder for future cross-user checks;
+    for v1 it is a no-op."""
+    return []
+
+
+HARD_INVARIANTS = (
+    inv_A_search_before_create,
+    inv_B_delete_known_id,
+    inv_D_plan_size_cap,
+    inv_F_no_duplicate_deletes,
+    inv_J_scope_match,
+)
+
+
+# --- Soft invariants ---
+
+
+def inv_E_no_duplicate_creates(ctx: ExtractionCtx) -> list[Violation]:  # noqa: N802
+    """Two CreateOps with identical content in one plan = oscillation smell."""
+    seen: dict[str, int] = {}
+    violations: list[Violation] = []
+    for i, op in enumerate(ctx.plan):
+        key = None
+        if isinstance(op, CreateUserProfileOp):
+            key = f"profile::{op.content}"
+        elif isinstance(op, CreateUserPlaybookOp):
+            key = f"playbook::{op.trigger}::{op.content}"
+        if key is None:
+            continue
+        if key in seen:
+            violations.append(
+                Violation(
+                    code="E",
+                    severity="soft",
+                    affected_op_indices=[i],
+                    msg=f"Duplicate create content at op {i}",
+                )
+            )
+        else:
+            seen[key] = i
+    return violations
+
+
+def inv_H_source_span_present(ctx: ExtractionCtx) -> list[Violation]:  # noqa: N802
+    """CreateOps must have non-whitespace source_span.
+
+    Schema enforces min_length=1, but whitespace-only slips through —
+    this is the secondary guard.
+    """
+    violations: list[Violation] = []
+    for i, op in enumerate(ctx.plan):
+        if (
+            isinstance(op, (CreateUserProfileOp, CreateUserPlaybookOp))
+            and not op.source_span.strip()
+        ):
+            violations.append(
+                Violation(
+                    code="H",
+                    severity="soft",
+                    affected_op_indices=[i],
+                    msg=f"Empty/whitespace source_span on create op {i}",
+                )
+            )
+    return violations
+
+
+def inv_K_deletes_without_creates(ctx: ExtractionCtx) -> list[Violation]:  # noqa: N802
+    """Plan with deletes but no creates is unusual — worth logging."""
+    has_delete = any(
+        isinstance(op, (DeleteUserProfileOp, DeleteUserPlaybookOp)) for op in ctx.plan
+    )
+    has_create = any(
+        isinstance(op, (CreateUserProfileOp, CreateUserPlaybookOp)) for op in ctx.plan
+    )
+    if has_delete and not has_create:
+        indices = [
+            i
+            for i, op in enumerate(ctx.plan)
+            if isinstance(op, (DeleteUserProfileOp, DeleteUserPlaybookOp))
+        ]
+        return [
+            Violation(
+                code="K",
+                severity="soft",
+                affected_op_indices=indices,
+                msg="Plan contains deletes without any matching creates",
+            )
+        ]
+    return []
+
+
+SOFT_INVARIANTS = (
+    inv_E_no_duplicate_creates,
+    inv_H_source_span_present,
+    inv_K_deletes_without_creates,
+)
+
+
+# --- Oscillation resolver ---
+
+
+def resolve_tentative_oscillations(plan: list) -> set[int]:
+    """Return plan indices to drop: create+delete-tentative pairs cancel.
+
+    When the agent creates an entity (issuing a tentative_id) and later
+    deletes that same tentative_id within the same plan, both ops are
+    dropped before invariants fire. This is the "oscillated self-correction"
+    pattern — the agent changed its mind mid-run.
+
+    The tentative_id format is ``tentative::<kind>::<plan_index_at_issue_time>``,
+    matching ``_next_tentative_id`` in tools.py which uses ``len(ctx.plan)``
+    (the plan length BEFORE the op is appended, i.e. the future index of the op).
+
+    Args:
+        plan: The accumulated list of PlanOp instances from ctx.plan.
+
+    Returns:
+        Set of plan indices to exclude from apply. Both the create and the
+        delete are dropped when a matching pair is found.
+    """
+    drop: set[int] = set()
+    pending_creates: dict[str, int] = {}
+    for i, op in enumerate(plan):
+        if isinstance(op, CreateUserProfileOp):
+            tentative_id = f"tentative::profile::{i}"
+            pending_creates[tentative_id] = i
+        elif isinstance(op, CreateUserPlaybookOp):
+            tentative_id = f"tentative::user_playbook::{i}"
+            pending_creates[tentative_id] = i
+        elif isinstance(op, (DeleteUserProfileOp, DeleteUserPlaybookOp)):
+            if op.id.startswith("tentative::") and op.id in pending_creates:
+                drop.add(pending_creates.pop(op.id))
+                drop.add(i)
+    return drop
+
+
+# --- commit_plan ---
+
+
+def commit_plan(
+    ctx: ExtractionCtx,
+    storage: object,
+    *,
+    outcome: str,  # Literal["finish_tool","max_steps","error"]
+) -> CommitResult:
+    """Run all invariants, then apply surviving ops atomically.
+
+    Args:
+        ctx: Populated ExtractionCtx from the agent loop.
+        storage: BaseStorage handle for apply.
+        outcome: How the loop terminated.
+
+    Returns:
+        CommitResult containing applied ops + all violations (hard + soft).
+    """
+    # Error outcome — discard everything, do not apply
+    if outcome == "error":
+        return CommitResult(applied=[], violations=[], outcome="error")
+
+    violations: list[Violation] = []
+    for check in HARD_INVARIANTS:
+        violations.extend(check(ctx))
+    for check in SOFT_INVARIANTS:
+        violations.extend(check(ctx))
+
+    dropped: set[int] = set()
+    # Oscillation resolver runs first: matching create+delete-tentative pairs
+    # cancel before invariants decide what to keep.
+    dropped.update(resolve_tentative_oscillations(ctx.plan))
+    for v in violations:
+        if v.severity == "hard":
+            dropped.update(v.affected_op_indices)
+
+    ops_to_apply = [op for i, op in enumerate(ctx.plan) if i not in dropped]
+
+    for v in violations:
+        logger.info(
+            "invariant_violation user_id=%s code=%s severity=%s op_indices=%s msg=%s",
+            ctx.user_id,
+            v.code,
+            v.severity,
+            v.affected_op_indices,
+            v.msg,
+        )
+
+    # Delegate actual storage writes to the tool-handler module (Task 5 wires this in).
+    # Lazy import so Task 3 can land before tools.py exists.
+    from reflexio.server.services.extraction.tools import (
+        apply_plan_op,  # noqa: PLC0415  # type: ignore[import-not-found]
+    )
+
+    for op in ops_to_apply:
+        apply_plan_op(op, storage, ctx)
+
+    return CommitResult(applied=ops_to_apply, violations=violations, outcome=outcome)  # type: ignore[arg-type]

package/plugin/vendor/reflexio/reflexio/server/services/extraction/outcome.py

@@ -0,0 +1,25 @@
+"""Shared extraction outcome types for resumable extraction paths."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class ExtractionOutcome[T]:
+    """Result wrapper returned by extractors that need explicit empty results."""
+
+    status: Literal["completed", "empty"]
+    items: list[T] = field(default_factory=list)
+    run_id: str | None = None
+
+    @classmethod
+    def completed(
+        cls, items: list[T], *, run_id: str | None = None
+    ) -> ExtractionOutcome[T]:
+        return cls(status="completed", items=items, run_id=run_id)
+
+    @classmethod
+    def empty(cls, *, run_id: str | None = None) -> ExtractionOutcome[T]:
+        return cls(status="empty", items=[], run_id=run_id)

package/plugin/vendor/reflexio/reflexio/server/services/extraction/pending_tool_call_dispatch.py

@@ -0,0 +1,358 @@
+"""Async information tools for resumable extraction runs."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Annotated, Any
+
+from pydantic import BaseModel, Field, field_validator
+
+from reflexio.models.config_schema import PendingToolCallConfig
+from reflexio.server.llm.tools import (
+    AsyncAccepted,
+    AsyncInfoTool,
+    AsyncRequestSpec,
+    Tool,
+)
+from reflexio.server.services.storage.storage_base import (
+    BaseStorage,
+    PendingToolCallRecord,
+    PendingToolCallStatus,
+    RunToolDependencyRecord,
+    build_pending_tool_call_dedup_key,
+    build_scope_hash,
+    human_feedback_scope,
+)
+from reflexio.server.usage_metrics import record_usage_event
+
+logger = logging.getLogger(__name__)
+
+
+class AskHumanArgs(BaseModel):
+    """Ask Agent Builder for missing extraction information and continue now."""
+
+    question: Annotated[str, Field(min_length=1)]
+    answer_format: str | None = None
+    tags: list[str] = Field(default_factory=list)
+
+    @field_validator("tags", mode="before")
+    @classmethod
+    def _coerce_tags(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return [tag.strip() for tag in value.split(",") if tag.strip()]
+        return value
+
+
+class AttachPendingInfoRequestArgs(BaseModel):
+    """Attach this run to a relevant pending Prior Knowledge request."""
+
+    pending_tool_call_id: Annotated[str, Field(min_length=1)]
+    why_relevant: str | None = None
+
+
+class PendingToolCallDispatcher:
+    """Dispatch newly-created pending tool calls to an external channel."""
+
+    def dispatch(self, record: PendingToolCallRecord) -> None:
+        raise NotImplementedError
+
+
+class NoopPendingToolCallDispatcher(PendingToolCallDispatcher):
+    """Local/test dispatcher that intentionally does nothing."""
+
+    def dispatch(self, _record: PendingToolCallRecord) -> None:
+        return None
+
+
+@dataclass(slots=True)
+class PendingToolCallToolContext:
+    storage: BaseStorage
+    run_id: str
+    org_id: str
+    extractor_kind: str
+    user_id: str | None = None
+    config: PendingToolCallConfig = field(default_factory=PendingToolCallConfig)
+    dispatcher: PendingToolCallDispatcher = field(
+        default_factory=NoopPendingToolCallDispatcher
+    )
+
+
+def _build_async_request_spec(
+    *,
+    args: AskHumanArgs,
+    ctx: PendingToolCallToolContext,
+) -> AsyncRequestSpec:
+    tool_config = ctx.config.for_tool("ask_human")
+    scope = human_feedback_scope(ctx.org_id)
+    return AsyncRequestSpec(
+        tool_name="ask_human",
+        dedup_key=build_pending_tool_call_dedup_key(
+            tool_name="ask_human",
+            question_text=args.question,
+            answer_format=args.answer_format,
+        ),
+        scope=scope,
+        question_text=args.question,
+        answer_format=args.answer_format,
+        args={
+            "question": args.question,
+            "answer_format": args.answer_format,
+        },
+        tags=args.tags,
+        cache_until_seconds=tool_config.dedup_cache_seconds,
+        valid_until_seconds=tool_config.prior_answer_valid_seconds,
+    )
+
+
+def _question_embedding(
+    storage: BaseStorage,
+    question_text: str,
+) -> list[float] | None:
+    get_embedding = getattr(storage, "_get_embedding", None)
+    if not callable(get_embedding):
+        return None
+    try:
+        embedding = get_embedding(question_text, purpose="document")
+    except TypeError:
+        embedding = get_embedding(question_text)
+    except Exception as exc:  # pragma: no cover - backend logs details elsewhere
+        logger.warning(
+            "event=pending_tool_call_embedding_failed error_type=%s error=%s",
+            type(exc).__name__,
+            exc,
+        )
+        return None
+    return embedding if isinstance(embedding, list) else None
+
+
+def handle_ask_human(
+    args: AskHumanArgs,
+    ctx: PendingToolCallToolContext,
+) -> AsyncAccepted:
+    if not ctx.run_id:
+        raise ValueError("ask_human requires a durable agent run_id")
+
+    current = datetime.now(UTC)
+    spec = _build_async_request_spec(args=args, ctx=ctx)
+    tool_config = ctx.config.for_tool(spec.tool_name)
+    # Observational soft cap only: intentionally read OUTSIDE the create/attach
+    # transaction. It never blocks or fails extraction (a small count race here
+    # would at most over/under-log the warning by one), so it does not need the
+    # per-scope transaction boundary that the dedup insert/attach uses.
+    unresolved_count = ctx.storage.count_unresolved_followup_dependencies(
+        org_id=ctx.org_id,
+        extractor_kind=ctx.extractor_kind,
+        tool_name=spec.tool_name,
+    )
+    if unresolved_count >= tool_config.max_pending_followups_per_scope:
+        logger.warning(
+            "event=pending_followup_soft_cap_exceeded org_id=%s extractor_kind=%s "
+            "tool_name=%s current_count=%d soft_cap=%d",
+            ctx.org_id,
+            ctx.extractor_kind,
+            spec.tool_name,
+            unresolved_count,
+            tool_config.max_pending_followups_per_scope,
+        )
+
+    record = PendingToolCallRecord(
+        id=f"ptc_{uuid.uuid4().hex}",
+        org_id=ctx.org_id,
+        user_id=ctx.user_id,
+        scope=spec.scope,
+        scope_hash=build_scope_hash(spec.scope),
+        tool_name=spec.tool_name,
+        dedup_key=spec.dedup_key,
+        status=PendingToolCallStatus.PENDING,
+        question_text=spec.question_text,
+        args=spec.args,
+        tags=spec.tags,
+        answer_format=spec.answer_format,
+        embedding=_question_embedding(ctx.storage, spec.question_text),
+        expires_at=current + timedelta(seconds=tool_config.pending_ttl_seconds),
+        cache_until=current + timedelta(seconds=spec.cache_until_seconds),
+    )
+    upsert = ctx.storage.create_or_attach_pending_tool_call(
+        record=record,
+        dependency=RunToolDependencyRecord(
+            run_id=ctx.run_id,
+            pending_tool_call_id=record.id,
+        ),
+        now=current,
+    )
+    record_usage_event(
+        org_id=ctx.org_id,
+        event_name="extraction_agent_async_info_requested",
+        event_category="extraction_agent",
+        user_id=ctx.user_id,
+        pipeline=ctx.extractor_kind,
+        outcome="created" if upsert.created else "deduped",
+        metadata={
+            "run_id": ctx.run_id,
+            "pending_tool_call_id": upsert.pending_tool_call.id,
+            "tool_name": upsert.pending_tool_call.tool_name,
+        },
+    )
+    if upsert.created:
+        ctx.dispatcher.dispatch(upsert.pending_tool_call)
+        logger.info(
+            "event=pending_tool_call_created org_id=%s user_id=%s "
+            "extractor_kind=%s run_id=%s pending_tool_call_id=%s "
+            "tool_name=%s",
+            ctx.org_id,
+            ctx.user_id,
+            ctx.extractor_kind,
+            ctx.run_id,
+            upsert.pending_tool_call.id,
+            upsert.pending_tool_call.tool_name,
+        )
+    else:
+        logger.info(
+            "event=extraction_agent_followup_attached org_id=%s user_id=%s "
+            "extractor_kind=%s run_id=%s pending_tool_call_id=%s "
+            "tool_name=%s deduped=true",
+            ctx.org_id,
+            ctx.user_id,
+            ctx.extractor_kind,
+            ctx.run_id,
+            upsert.pending_tool_call.id,
+            upsert.pending_tool_call.tool_name,
+        )
+
+    return AsyncAccepted(
+        pending_tool_call_id=upsert.pending_tool_call.id,
+        result={
+            "status": "request_pending",
+            "pending_tool_call_id": upsert.pending_tool_call.id,
+            "instruction": (
+                "Continue extraction using currently available evidence. "
+                "This run will be resumed when the answer arrives."
+            ),
+        },
+    )
+
+
+def handle_attach_pending_info_request(
+    args: AttachPendingInfoRequestArgs,
+    ctx: PendingToolCallToolContext,
+) -> dict[str, Any]:
+    if not ctx.run_id:
+        raise ValueError("attach_pending_info_request requires a durable agent run_id")
+
+    record = ctx.storage.get_pending_tool_call(args.pending_tool_call_id)
+    expected_scope = human_feedback_scope(ctx.org_id)
+    current = datetime.now(UTC)
+    if (
+        record is None
+        or record.org_id != ctx.org_id
+        or record.tool_name != "ask_human"
+        or record.scope_hash != build_scope_hash(expected_scope)
+    ):
+        return {
+            "status": "not_found",
+            "instruction": (
+                "The referenced Prior Knowledge request is unavailable. "
+                "Continue extraction, or call ask_human if the information is still needed."
+            ),
+        }
+
+    if record.status == PendingToolCallStatus.RESOLVED:
+        if record.valid_until is not None and record.valid_until <= current:
+            return {
+                "status": "expired",
+                "instruction": (
+                    "The referenced answer is no longer valid. Continue extraction, "
+                    "or call ask_human if the information is still needed."
+                ),
+            }
+        return {
+            "status": "already_resolved",
+            "pending_tool_call_id": record.id,
+            "question": record.question_text,
+            "result": record.result or {},
+            "instruction": (
+                "Use this result only if it is relevant to the current extraction."
+            ),
+        }
+
+    if record.status != PendingToolCallStatus.PENDING or (
+        record.expires_at is not None and record.expires_at <= current
+    ):
+        return {
+            "status": "unavailable",
+            "instruction": (
+                "The referenced request is no longer pending. Continue extraction, "
+                "or call ask_human if the information is still needed."
+            ),
+        }
+
+    ctx.storage.attach_run_tool_dependency(
+        RunToolDependencyRecord(
+            run_id=ctx.run_id,
+            pending_tool_call_id=record.id,
+        )
+    )
+    logger.info(
+        "event=extraction_agent_followup_attached org_id=%s user_id=%s "
+        "extractor_kind=%s run_id=%s pending_tool_call_id=%s "
+        "tool_name=%s",
+        ctx.org_id,
+        ctx.user_id,
+        ctx.extractor_kind,
+        ctx.run_id,
+        record.id,
+        record.tool_name,
+    )
+    return {
+        "status": "attached_for_followup",
+        "pending_tool_call_id": record.id,
+        "instruction": (
+            "Continue extraction using currently available evidence. "
+            "This run will be resumed when the pending answer arrives."
+        ),
+    }
+
+
+def _handle_ask_human_tool(args: BaseModel, ctx: Any) -> AsyncAccepted:
+    if not isinstance(args, AskHumanArgs):
+        raise TypeError(f"Expected AskHumanArgs, got {type(args).__name__}")
+    ctx = getattr(ctx, "extra_tool_context", ctx)
+    if not isinstance(ctx, PendingToolCallToolContext):
+        raise TypeError(
+            f"Expected PendingToolCallToolContext, got {type(ctx).__name__}"
+        )
+    return handle_ask_human(args, ctx)
+
+
+def _handle_attach_pending_info_request_tool(
+    args: BaseModel, ctx: Any
+) -> dict[str, Any]:
+    if not isinstance(args, AttachPendingInfoRequestArgs):
+        raise TypeError(
+            f"Expected AttachPendingInfoRequestArgs, got {type(args).__name__}"
+        )
+    ctx = getattr(ctx, "extra_tool_context", ctx)
+    if not isinstance(ctx, PendingToolCallToolContext):
+        raise TypeError(
+            f"Expected PendingToolCallToolContext, got {type(ctx).__name__}"
+        )
+    return handle_attach_pending_info_request(args, ctx)
+
+
+def create_ask_human_tool() -> AsyncInfoTool:
+    return AsyncInfoTool(
+        name="ask_human",
+        args_model=AskHumanArgs,
+        handler=_handle_ask_human_tool,
+    )
+
+
+def create_attach_pending_info_request_tool() -> Tool:
+    return Tool(
+        name="attach_pending_info_request",
+        args_model=AttachPendingInfoRequestArgs,
+        handler=_handle_attach_pending_info_request_tool,
+    )