shellbrain 0.1.0__py3-none-any.whl

app/periphery/identity/codex_runtime.py

@@ -0,0 +1,32 @@
+"""Codex runtime identity helpers."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Sequence
+
+from app.core.entities.identity import CallerIdentity, IdentityTrustLevel
+from app.periphery.episodes.codex import resolve_codex_transcript_path
+
+
+def resolve_codex_caller_identity() -> CallerIdentity | None:
+    """Resolve one trusted Codex caller from the runtime environment when present."""
+
+    thread_id = os.getenv("CODEX_THREAD_ID")
+    if not thread_id:
+        return None
+    return CallerIdentity(
+        host_app="codex",
+        host_session_key=thread_id,
+        trust_level=IdentityTrustLevel.TRUSTED,
+    )
+
+
+def resolve_codex_transcript_for_caller(*, caller_identity: CallerIdentity, search_roots: Sequence[Path]) -> Path:
+    """Resolve the Codex transcript path for one trusted caller."""
+
+    return resolve_codex_transcript_path(
+        host_session_key=caller_identity.host_session_key,
+        search_roots=list(search_roots),
+    )

app/periphery/identity/compatibility.py

@@ -0,0 +1,38 @@
+"""Compatibility-safe caller-identity errors with concrete remediation guidance."""
+
+from __future__ import annotations
+
+from app.core.contracts.errors import ErrorCode, ErrorDetail
+
+
+def host_hook_missing_error() -> ErrorDetail:
+    """Return the canonical error for missing Claude hook identity injection."""
+
+    return ErrorDetail(
+        code=ErrorCode.HOST_HOOK_MISSING,
+        message="Claude Code runtime detected but Shellbrain hook identity is missing. Run `shellbrain admin install-claude-hook` in this repo and restart Claude Code.",
+    )
+
+
+def host_identity_unsupported_error() -> ErrorDetail:
+    """Return the canonical error for unsupported host identity layouts."""
+
+    return ErrorDetail(
+        code=ErrorCode.HOST_IDENTITY_UNSUPPORTED,
+        message="This host runtime does not expose enough identity data for Shellbrain to isolate the caller safely.",
+    )
+
+
+def host_identity_drifted_error(*, caller_id: str) -> ErrorDetail:
+    """Return the canonical error for trusted identities that can no longer be resolved."""
+
+    return ErrorDetail(
+        code=ErrorCode.HOST_IDENTITY_DRIFTED,
+        message=f"Trusted caller identity drifted and could not be resolved for `{caller_id}`. Verify the host thread/session still exists and rerun `events`.",
+    )
+
+
+def transcript_source_not_found_error(*, message: str) -> ErrorDetail:
+    """Return the canonical error for transcript-source resolution failures."""
+
+    return ErrorDetail(code=ErrorCode.TRANSCRIPT_SOURCE_NOT_FOUND, message=message)

app/periphery/identity/resolver.py

@@ -0,0 +1,163 @@
+"""Resolve caller identity and exact event sources across supported hosts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+from app.core.contracts.errors import ErrorDetail
+from app.core.entities.identity import CallerIdentity, IdentityTrustLevel
+from app.periphery.episodes.source_discovery import SUPPORTED_HOSTS, default_search_roots
+from app.periphery.identity.claude_runtime import (
+    detect_claude_runtime_without_hook,
+    resolve_trusted_claude_caller_identity,
+    resolve_trusted_claude_transcript_path,
+)
+from app.periphery.identity.codex_runtime import (
+    resolve_codex_caller_identity,
+    resolve_codex_transcript_for_caller,
+)
+from app.periphery.identity.compatibility import (
+    host_hook_missing_error,
+    host_identity_drifted_error,
+    host_identity_unsupported_error,
+)
+from app.periphery.telemetry.session_selection import discover_events_candidate
+
+
+@dataclass(frozen=True)
+class CallerIdentityResolution:
+    """Resolved caller identity plus any compatibility error and trusted path hint."""
+
+    caller_identity: CallerIdentity | None
+    transcript_path_hint: Path | None = None
+    error: ErrorDetail | None = None
+
+
+@dataclass(frozen=True)
+class ResolvedEventsSource:
+    """Resolved exact or fallback events source for one operation."""
+
+    caller_identity: CallerIdentity | None
+    host_app: str | None = None
+    host_session_key: str | None = None
+    canonical_thread_id: str | None = None
+    transcript_path: Path | None = None
+    search_roots: tuple[Path, ...] = ()
+    matching_candidate_count: int = 0
+    selection_ambiguous: bool = False
+    trusted: bool = False
+    error: ErrorDetail | None = None
+
+
+def resolve_caller_identity() -> CallerIdentityResolution:
+    """Resolve caller identity from trusted runtimes before falling back to none."""
+
+    codex_identity = resolve_codex_caller_identity()
+    if codex_identity is not None:
+        return CallerIdentityResolution(caller_identity=codex_identity)
+
+    claude_identity = resolve_trusted_claude_caller_identity()
+    if claude_identity is not None:
+        if claude_identity.trust_level == IdentityTrustLevel.UNSUPPORTED:
+            return CallerIdentityResolution(caller_identity=None, error=host_identity_unsupported_error())
+        return CallerIdentityResolution(
+            caller_identity=claude_identity,
+            transcript_path_hint=resolve_trusted_claude_transcript_path(),
+        )
+
+    if detect_claude_runtime_without_hook():
+        return CallerIdentityResolution(caller_identity=None, error=host_hook_missing_error())
+    return CallerIdentityResolution(caller_identity=None)
+
+
+def resolve_trusted_events_source(
+    *,
+    caller_identity: CallerIdentity,
+    repo_root: Path,
+    search_roots_by_host: dict[str, list[Path]] | None = None,
+) -> ResolvedEventsSource:
+    """Resolve the exact transcript source for one trusted caller."""
+
+    search_roots = _search_roots_for_host(
+        repo_root=repo_root,
+        host_app=caller_identity.host_app,
+        search_roots_by_host=search_roots_by_host,
+    )
+    try:
+        if caller_identity.host_app == "codex":
+            transcript_path = resolve_codex_transcript_for_caller(
+                caller_identity=caller_identity,
+                search_roots=search_roots,
+            )
+        elif caller_identity.host_app == "claude_code":
+            transcript_path = resolve_trusted_claude_transcript_path()
+            if transcript_path is None:
+                return ResolvedEventsSource(
+                    caller_identity=caller_identity,
+                    error=host_identity_drifted_error(caller_id=caller_identity.canonical_id or ""),
+                )
+        else:
+            return ResolvedEventsSource(caller_identity=caller_identity, error=host_identity_unsupported_error())
+    except FileNotFoundError:
+        return ResolvedEventsSource(
+            caller_identity=caller_identity,
+            error=host_identity_drifted_error(caller_id=caller_identity.canonical_id or ""),
+        )
+
+    return ResolvedEventsSource(
+        caller_identity=caller_identity,
+        host_app=caller_identity.host_app,
+        host_session_key=caller_identity.host_session_key,
+        canonical_thread_id=caller_identity.canonical_id,
+        transcript_path=transcript_path,
+        search_roots=tuple(search_roots),
+        matching_candidate_count=1,
+        selection_ambiguous=False,
+        trusted=True,
+    )
+
+
+def discover_untrusted_events_candidate(
+    *,
+    repo_root: Path,
+    search_roots_by_host: dict[str, list[Path]] | None = None,
+) -> ResolvedEventsSource | None:
+    """Discover the newest repo-matching host session as an untrusted fallback."""
+
+    discovery = discover_events_candidate(repo_root=repo_root, search_roots_by_host=search_roots_by_host)
+    if discovery is None:
+        return None
+    caller_identity = CallerIdentity(
+        host_app=discovery.host_app,
+        host_session_key=discovery.host_session_key,
+        canonical_id=discovery.summary.selected_thread_id,
+        trust_level=IdentityTrustLevel.UNTRUSTED,
+    )
+    return ResolvedEventsSource(
+        caller_identity=caller_identity,
+        host_app=discovery.host_app,
+        host_session_key=discovery.host_session_key,
+        canonical_thread_id=discovery.summary.selected_thread_id,
+        transcript_path=discovery.transcript_path,
+        search_roots=tuple(discovery.search_roots),
+        matching_candidate_count=discovery.summary.matching_candidate_count,
+        selection_ambiguous=discovery.summary.selection_ambiguous,
+        trusted=False,
+    )
+
+
+def _search_roots_for_host(
+    *,
+    repo_root: Path,
+    host_app: str,
+    search_roots_by_host: dict[str, list[Path]] | None,
+) -> list[Path]:
+    """Resolve bounded search roots for one host with optional test overrides."""
+
+    if search_roots_by_host is not None:
+        return [Path(path) for path in search_roots_by_host.get(host_app, [])]
+    if host_app not in SUPPORTED_HOSTS:
+        return [repo_root]
+    return default_search_roots(repo_root=repo_root, host_app=host_app)

app/periphery/session_state/__init__.py

@@ -0,0 +1 @@
+"""Repo-local per-caller session-state storage."""

app/periphery/session_state/file_store.py

@@ -0,0 +1,100 @@
+"""JSON file-backed implementation of repo-local per-caller session state."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+from app.core.entities.session_state import SessionState
+from app.core.interfaces.session_state_store import ISessionStateStore
+
+
+class FileSessionStateStore(ISessionStateStore):
+    """Persist trusted per-caller session state under one repo-local runtime directory."""
+
+    def load(self, *, repo_root: Path, caller_id: str) -> SessionState | None:
+        """Load one caller state when the corresponding file exists."""
+
+        path = self._path_for(repo_root=repo_root, caller_id=caller_id)
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (FileNotFoundError, json.JSONDecodeError):
+            return None
+        if not isinstance(payload, dict):
+            return None
+        return SessionState(**payload)
+
+    def save(self, *, repo_root: Path, state: SessionState) -> None:
+        """Persist one caller state under its canonical caller id."""
+
+        path = self._path_for(repo_root=repo_root, caller_id=state.caller_id, host_app=state.host_app)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps(asdict(state), indent=2, sort_keys=True)
+        with NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, delete=False) as handle:
+            handle.write(payload)
+            temp_path = Path(handle.name)
+        os.replace(temp_path, path)
+
+    def delete(self, *, repo_root: Path, caller_id: str) -> None:
+        """Delete one caller state when its file exists."""
+
+        path = self._path_for(repo_root=repo_root, caller_id=caller_id)
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            return
+
+    def list(self, *, repo_root: Path) -> list[SessionState]:
+        """Return every parseable caller state stored for the repo root."""
+
+        session_root = Path(repo_root).resolve() / ".shellbrain" / "session_state"
+        if not session_root.exists():
+            return []
+        states: list[SessionState] = []
+        for path in session_root.rglob("*.json"):
+            try:
+                payload = json.loads(path.read_text(encoding="utf-8"))
+            except (FileNotFoundError, json.JSONDecodeError):
+                continue
+            if not isinstance(payload, dict):
+                continue
+            states.append(SessionState(**payload))
+        return states
+
+    def gc(self, *, repo_root: Path, older_than_iso: str) -> list[str]:
+        """Delete caller states last seen before the given cutoff."""
+
+        cutoff = _parse_iso(older_than_iso)
+        deleted: list[str] = []
+        for state in self.list(repo_root=repo_root):
+            try:
+                last_seen = _parse_iso(state.last_seen_at)
+            except ValueError:
+                last_seen = datetime.min.replace(tzinfo=timezone.utc)
+            if last_seen >= cutoff:
+                continue
+            self.delete(repo_root=repo_root, caller_id=state.caller_id)
+            deleted.append(state.caller_id)
+        return deleted
+
+    def _path_for(self, *, repo_root: Path, caller_id: str, host_app: str | None = None) -> Path:
+        """Return the storage path for one caller id."""
+
+        repo_root = Path(repo_root).resolve()
+        if host_app is None:
+            host_app = caller_id.split(":", 1)[0]
+        filename = f"{caller_id.replace(':', '__')}.json"
+        return repo_root / ".shellbrain" / "session_state" / host_app / filename
+
+
+def _parse_iso(value: str) -> datetime:
+    """Parse one ISO timestamp into a timezone-aware datetime."""
+
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)

app/periphery/telemetry/__init__.py

@@ -0,0 +1,33 @@
+"""Internal runtime context helpers for per-command telemetry capture."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+
+from app.core.entities.runtime_context import RuntimeContext
+
+
+_OPERATION_TELEMETRY_CONTEXT: ContextVar[RuntimeContext | None] = ContextVar(
+    "shellbrain_operation_telemetry_context",
+    default=None,
+)
+
+
+def get_operation_telemetry_context() -> RuntimeContext | None:
+    """Return the current command-level telemetry context when one exists."""
+
+    return _OPERATION_TELEMETRY_CONTEXT.get()
+
+
+def set_operation_telemetry_context(
+    context: RuntimeContext,
+) -> Token[RuntimeContext | None]:
+    """Install one command-level telemetry context for the current execution flow."""
+
+    return _OPERATION_TELEMETRY_CONTEXT.set(context)
+
+
+def reset_operation_telemetry_context(token: Token[RuntimeContext | None]) -> None:
+    """Restore the previous telemetry context after a command finishes."""
+
+    _OPERATION_TELEMETRY_CONTEXT.reset(token)

app/periphery/telemetry/operation_summary.py

@@ -0,0 +1,299 @@
+"""Helpers for assembling operation telemetry records from handler inputs and outputs."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from app.core.contracts.errors import ErrorCode
+from app.core.contracts.requests import MemoryBatchUpdateRequest, MemoryCreateRequest, MemoryReadRequest, MemoryUpdateRequest
+from app.core.entities.runtime_context import RuntimeContext
+from app.core.entities.telemetry import (
+    OperationInvocationRecord,
+    ReadResultItemRecord,
+    ReadSummaryRecord,
+    SessionSelectionSummary,
+    WriteEffectItemRecord,
+    WriteSummaryRecord,
+)
+
+
+def build_operation_invocation_record(
+    *,
+    command: str,
+    repo_id: str,
+    runtime_context: RuntimeContext,
+    selection_summary: SessionSelectionSummary,
+    result: dict[str, Any],
+    error_stage: str | None,
+    total_latency_ms: int,
+) -> OperationInvocationRecord:
+    """Build the parent invocation row from one finished handler result."""
+
+    first_error = _first_error(result)
+    caller_identity = runtime_context.caller_identity
+    guidance_codes = _guidance_codes(result)
+    return OperationInvocationRecord(
+        id=runtime_context.invocation_id,
+        command=command,
+        repo_id=repo_id,
+        repo_root=runtime_context.repo_root,
+        no_sync=runtime_context.no_sync,
+        caller_id=caller_identity.canonical_id if caller_identity is not None else None,
+        caller_trust_level=caller_identity.trust_level.value if caller_identity is not None else None,
+        identity_failure_code=runtime_context.caller_identity_error.code.value
+        if runtime_context.caller_identity_error is not None
+        else None,
+        selected_host_app=selection_summary.selected_host_app,
+        selected_host_session_key=selection_summary.selected_host_session_key,
+        selected_thread_id=selection_summary.selected_thread_id,
+        selected_episode_id=selection_summary.selected_episode_id,
+        matching_candidate_count=selection_summary.matching_candidate_count,
+        selection_ambiguous=selection_summary.selection_ambiguous,
+        outcome=str(result.get("status") or "error"),
+        error_stage=error_stage,
+        error_code=first_error["code"],
+        error_message=first_error["message"],
+        total_latency_ms=total_latency_ms,
+        poller_start_attempted=False,
+        poller_started=False,
+        guidance_codes=guidance_codes,
+        created_at=datetime.now(timezone.utc),
+    )
+
+
+def build_read_summary_records(
+    *,
+    invocation_id: str,
+    agent_payload: dict[str, Any],
+    request: MemoryReadRequest,
+    pack: dict[str, Any],
+) -> tuple[ReadSummaryRecord, list[ReadResultItemRecord]]:
+    """Build one read summary row and one item row per displayed memory."""
+
+    direct = list(pack.get("direct", []))
+    explicit_related = list(pack.get("explicit_related", []))
+    implicit_related = list(pack.get("implicit_related", []))
+    items: list[ReadResultItemRecord] = []
+    ordinal = 1
+    for section_name, bucket in (
+        ("direct", direct),
+        ("explicit_related", explicit_related),
+        ("implicit_related", implicit_related),
+    ):
+        for item in bucket:
+            items.append(
+                ReadResultItemRecord(
+                    invocation_id=invocation_id,
+                    ordinal=ordinal,
+                    memory_id=str(item["memory_id"]),
+                    kind=str(item["kind"]),
+                    section=section_name,
+                    priority=ordinal,
+                    why_included=str(item.get("why_included") or ""),
+                    anchor_memory_id=_optional_string(item.get("anchor_memory_id")),
+                    relation_type=_optional_string(item.get("relation_type")),
+                )
+            )
+            ordinal += 1
+
+    summary = ReadSummaryRecord(
+        invocation_id=invocation_id,
+        query_text=request.query,
+        mode=request.mode,
+        requested_limit=agent_payload.get("limit") if isinstance(agent_payload.get("limit"), int) else None,
+        effective_limit=int(request.limit or len(items) or 0),
+        include_global=request.include_global,
+        kinds_filter=list(request.kinds) if request.kinds is not None else None,
+        direct_count=len(direct),
+        explicit_related_count=len(explicit_related),
+        implicit_related_count=len(implicit_related),
+        total_returned=len(items),
+        zero_results=len(items) == 0,
+        created_at=datetime.now(timezone.utc),
+    )
+    return summary, items
+
+
+def build_write_summary_records(
+    *,
+    invocation_id: str,
+    command: str,
+    request: MemoryCreateRequest | MemoryUpdateRequest | MemoryBatchUpdateRequest,
+    planned_side_effects: list[dict[str, Any]],
+) -> tuple[WriteSummaryRecord, list[WriteEffectItemRecord]]:
+    """Build one write summary row and one compact effect row per planned side effect."""
+
+    created_memory_count = 0
+    archived_memory_count = 0
+    utility_observation_count = 0
+    association_effect_count = 0
+    fact_update_count = 0
+    effect_items: list[WriteEffectItemRecord] = []
+
+    for ordinal, effect in enumerate(planned_side_effects, start=1):
+        effect_type = str(effect["effect_type"])
+        params = effect["params"]
+        assert isinstance(params, dict)
+        if effect_type == "memory.create":
+            created_memory_count += 1
+        elif effect_type == "memory.archive_state" and bool(params.get("archived")):
+            archived_memory_count += 1
+        elif effect_type == "utility_observation.append":
+            utility_observation_count += 1
+        elif effect_type == "association.upsert_and_observe":
+            association_effect_count += 1
+        elif effect_type == "fact_update.create":
+            fact_update_count += 1
+
+        effect_items.append(
+            WriteEffectItemRecord(
+                invocation_id=invocation_id,
+                ordinal=ordinal,
+                effect_type=effect_type,
+                repo_id=str(getattr(request, "repo_id")),
+                primary_memory_id=_primary_memory_id(params),
+                secondary_memory_id=_secondary_memory_id(params),
+                params_json=_compact_effect_params(params),
+            )
+        )
+
+    if isinstance(request, MemoryCreateRequest):
+        evidence_ref_count = len(request.memory.evidence_refs)
+        target_memory_id = _target_memory_id_from_create(planned_side_effects)
+        target_kind = request.memory.kind
+        update_type = None
+        scope = request.memory.scope
+    elif isinstance(request, MemoryBatchUpdateRequest):
+        evidence_ref_count = sum(len(item.update.evidence_refs or []) for item in request.updates)
+        target_memory_id = request.updates[0].update.problem_id
+        target_kind = None
+        update_type = "utility_vote_batch"
+        scope = None
+    else:
+        evidence_ref_count = len(getattr(request.update, "evidence_refs", []) or [])
+        target_memory_id = request.memory_id
+        target_kind = None
+        update_type = request.update.type
+        scope = None
+
+    summary = WriteSummaryRecord(
+        invocation_id=invocation_id,
+        operation_command=command,
+        target_memory_id=target_memory_id,
+        target_kind=target_kind,
+        update_type=update_type,
+        scope=scope,
+        evidence_ref_count=evidence_ref_count,
+        planned_effect_count=len(planned_side_effects),
+        created_memory_count=created_memory_count,
+        archived_memory_count=archived_memory_count,
+        utility_observation_count=utility_observation_count,
+        association_effect_count=association_effect_count,
+        fact_update_count=fact_update_count,
+        created_at=datetime.now(timezone.utc),
+    )
+    return summary, effect_items
+
+
+def infer_error_stage_from_errors(errors: list[dict[str, Any]], *, default_stage: str) -> str:
+    """Map structured error codes to telemetry stages when validation failed."""
+
+    if not errors:
+        return default_stage
+    code = errors[0].get("code")
+    normalized = code.value if isinstance(code, ErrorCode) else str(code)
+    if normalized == ErrorCode.SCHEMA_ERROR.value and default_stage == "schema_validation":
+        return "schema_validation"
+    if normalized == ErrorCode.SCHEMA_ERROR.value and default_stage == "contract_validation":
+        return "contract_validation"
+    if normalized == ErrorCode.SEMANTIC_ERROR.value:
+        return "semantic_validation"
+    if normalized == ErrorCode.INTEGRITY_ERROR.value:
+        return "integrity_validation"
+    return default_stage
+
+
+def _first_error(result: dict[str, Any]) -> dict[str, str | None]:
+    """Return the first response error in a stable telemetry-friendly shape."""
+
+    errors = result.get("errors")
+    if not isinstance(errors, list) or not errors:
+        return {"code": None, "message": None}
+    first = errors[0]
+    if not isinstance(first, dict):
+        return {"code": None, "message": str(first)}
+    code = first.get("code")
+    normalized_code = code.value if isinstance(code, ErrorCode) else (str(code) if code is not None else None)
+    message = first.get("message")
+    return {
+        "code": normalized_code,
+        "message": str(message) if message is not None else None,
+    }
+
+
+def _guidance_codes(result: dict[str, Any]) -> list[str]:
+    """Return stable guidance codes from one successful result."""
+
+    data = result.get("data")
+    if not isinstance(data, dict):
+        return []
+    guidance = data.get("guidance")
+    if not isinstance(guidance, list):
+        return []
+    codes: list[str] = []
+    for item in guidance:
+        if not isinstance(item, dict):
+            continue
+        code = item.get("code")
+        if isinstance(code, str):
+            codes.append(code)
+    return codes
+
+
+def _target_memory_id_from_create(planned_side_effects: list[dict[str, Any]]) -> str:
+    """Extract the created memory id from one create side-effect plan."""
+
+    for effect in planned_side_effects:
+        if str(effect.get("effect_type")) != "memory.create":
+            continue
+        params = effect.get("params")
+        if isinstance(params, dict) and isinstance(params.get("memory_id"), str):
+            return str(params["memory_id"])
+    raise ValueError("Create telemetry expected one memory.create side effect.")
+
+
+def _compact_effect_params(params: dict[str, Any]) -> dict[str, Any]:
+    """Drop bulky fields so telemetry stores compact, queryable side-effect metadata."""
+
+    return {
+        str(key): value
+        for key, value in params.items()
+        if key not in {"text", "vector"}
+    }
+
+
+def _primary_memory_id(params: dict[str, Any]) -> str | None:
+    """Extract the primary memory identifier from one side-effect payload when present."""
+
+    for key in ("memory_id", "from_memory_id", "old_fact_id", "problem_id", "change_id"):
+        value = params.get(key)
+        if isinstance(value, str):
+            return value
+    return None
+
+
+def _secondary_memory_id(params: dict[str, Any]) -> str | None:
+    """Extract the secondary memory identifier from one side-effect payload when present."""
+
+    for key in ("to_memory_id", "new_fact_id", "attempt_id"):
+        value = params.get(key)
+        if isinstance(value, str):
+            return value
+    return None
+
+
+def _optional_string(value: object) -> str | None:
+    """Return a string value or None when the field is absent."""
+
+    return str(value) if isinstance(value, str) else None