@ngocsangairvds/vsaf 4.0.5 → 4.0.7

package/skills/vds-skill/vds-scripts/vds_agent_core/src/vds_agent_core/workflows/protocols.py

@@ -0,0 +1,81 @@
+"""WorkflowProvider Protocol — host-side contract for cron-driven workflows.
+
+Defined by ADR-DCP-1 of the vds-scheduler spec
+(v0.2.0). A `WorkflowProvider` is anything that can register workflow aliases
+and cron schedules for a durable workflow framework (currently DBOS in the
+VDS scheduler_orchestrator). Workflow-provider packages (e.g.,
+audit_orchestrator) receive an instance of WorkflowProvider as the argument
+to their entry-point `register(provider)` callable, and use it to register
+aliases + schedules without importing scheduler internals directly.
+
+Both methods are idempotent — implementations MUST silently ignore the
+host's "duplicate alias" / "duplicate schedule" errors so that providers
+can call `register()` from a lifespan that runs on every container start.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class WorkflowProvider(Protocol):
+    """Host-side contract that scheduler-like orchestrators expose to workflow
+    providers (entry-points group `vds.workflows`).
+
+    Stability: This Protocol is part of the v0.2.0 contract for entry-points
+    group `vds.workflows`. Breaking changes (method signature changes,
+    removals) require a major bump of the `vds_agent_core` package. Additive
+    changes (new methods, or new keyword-only args with defaults) are
+    non-breaking.
+    """
+
+    def register_workflow_alias(
+        self,
+        *,
+        alias: str,
+        workflow_fqn: str,
+        owner: str,
+    ) -> None:
+        """Map a stable alias to a fully-qualified `@DBOS.workflow` function.
+
+        Args:
+            alias: Stable name used by `register_schedule(workflow_alias=...)`
+                (e.g., "audit.drift.weekly").
+            workflow_fqn: Dotted import path to the workflow function
+                (e.g., "vds_audit_orchestrator.workflows.audit_drift_scan.audit_drift_scan").
+            owner: Workflow-owner package name (e.g., "audit_orchestrator").
+
+        Idempotent: implementations MUST silently swallow any
+        "duplicate alias" error from the host registry.
+        """
+        ...
+
+    def register_schedule(
+        self,
+        *,
+        schedule_id: str,
+        workflow_alias: str,
+        cron: str,
+        owner: str,
+        queue_name: str = "agent-default",
+        context_json: dict[str, Any] | None = None,
+    ) -> None:
+        """Register a cron-driven schedule that fires `workflow_alias`.
+
+        Args:
+            schedule_id: Stable identifier for the schedule
+                (e.g., "audit-drift-weekly").
+            workflow_alias: Alias previously registered via
+                `register_workflow_alias` that points to the actual
+                `@DBOS.workflow` function.
+            cron: Cron expression (5-field standard form, e.g., "0 2 * * MON").
+            owner: Workflow-owner package name (e.g., "audit_orchestrator").
+            queue_name: Host-defined queue name. Defaults to "agent-default".
+            context_json: JSON-serialisable keyword arguments passed to the
+                workflow function on each tick. None when no kwargs needed.
+
+        Idempotent: implementations MUST silently swallow any
+        "duplicate schedule" error from the host registry.
+        """
+        ...

package/skills/vds-skill/vds-scripts/vds_agent_core/tests/conftest.py

@@ -0,0 +1,62 @@
+"""Test isolation for vds_agent_core observability wiring.
+
+Phase 3 wiring (TSK-P3-Theta) makes ``AgentTracer.__post_init__`` auto-register
+a :class:`JsonlUsageExporter` whenever ``VDS_LLM_USAGE_JSONL_ENABLED`` is
+unset or truthy. That default is correct for production but would have every
+test that constructs an ``AgentTracer`` start writing to ``~/.vds/cache/``.
+
+This conftest:
+
+* **Disables** auto-registration globally for the test session by pinning
+  ``VDS_LLM_USAGE_JSONL_ENABLED=false`` before any test imports the tracer.
+* **Redirects** the JSONL cache directory to a per-session ``tmp_path`` via
+  ``VDS_LLM_USAGE_DIR`` so even tests that explicitly opt-in stay sandboxed.
+* Exposes a ``llm_usage_jsonl_dir`` fixture for tests that want a clean
+  per-test directory plus the auto-register flag turned ON.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+# Pin the disable flag *before* anything imports vds_agent_core.observability.
+# autouse=True at session scope is the standard way to do this — but that runs
+# AFTER collection, by which time tracer modules may already be imported. The
+# safest belt-and-braces approach is to also touch os.environ at module import
+# time (i.e. now) so the import-time read in `_jsonl_auto_register_enabled`
+# sees the disable.
+os.environ.setdefault("VDS_LLM_USAGE_JSONL_ENABLED", "false")
+
+
+@pytest.fixture(autouse=True)
+def _isolate_llm_usage_env(
+    tmp_path_factory: pytest.TempPathFactory,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Force every test into a sandboxed JSONL cache directory.
+
+    Even if a test forgets to disable the auto-register flag, writes will
+    land in a ``tmp_path``-derived directory, never in ``~/.vds/cache/``.
+    """
+    sandbox = tmp_path_factory.mktemp("vds-llm-usage-sandbox")
+    monkeypatch.setenv("VDS_LLM_USAGE_DIR", str(sandbox))
+    monkeypatch.setenv("VDS_LLM_USAGE_JSONL_ENABLED", "false")
+
+
+@pytest.fixture
+def llm_usage_jsonl_dir(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> Path:
+    """Per-test JSONL directory with auto-register turned ON.
+
+    Returns the directory; tests can construct an ``AgentTracer`` and
+    verify a JSONL file appears under it.
+    """
+    target = tmp_path / "llm-usage"
+    monkeypatch.setenv("VDS_LLM_USAGE_DIR", str(target))
+    monkeypatch.setenv("VDS_LLM_USAGE_JSONL_ENABLED", "true")
+    return target

package/skills/vds-skill/vds-scripts/vds_agent_core/tests/integration/test_audit_loop_hooks_integration.py

@@ -0,0 +1,135 @@
+"""Cross-orchestrator integration tests for AuditLoopHooks ↔ LoopBehaviorHooks.
+
+Phase 9d Contract 2: ``AuditLoopHooks`` from
+``vds_audit_orchestrator.agents.audit_loop_hooks`` must structurally satisfy
+the ``LoopBehaviorHooks`` Protocol from ``vds_agent_core.agents.hooks``.
+The Protocol is ``@runtime_checkable``, so isinstance() must return True
+and every Protocol method must return audit-specific values when invoked.
+
+Skipped gracefully if ``vds_audit_orchestrator`` is not on PYTHONPATH.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+pytest.importorskip(
+    "vds_audit_orchestrator",
+    reason="audit integration tests require vds_audit_orchestrator on PYTHONPATH",
+)
+
+
+@pytest.fixture
+def audit_hooks():
+    """Construct a fresh AuditLoopHooks instance for each test."""
+    from vds_audit_orchestrator.agents.audit_loop_hooks import AuditLoopHooks
+
+    return AuditLoopHooks()
+
+
+class TestProtocolSatisfaction:
+    """AuditLoopHooks must satisfy LoopBehaviorHooks at runtime."""
+
+    def test_isinstance_passes_for_audit_hooks(self, audit_hooks) -> None:
+        """isinstance check against the runtime_checkable Protocol passes."""
+        from vds_agent_core.agents.hooks import LoopBehaviorHooks
+
+        assert isinstance(audit_hooks, LoopBehaviorHooks)
+
+    def test_audit_hooks_does_not_subclass_noophooks(self, audit_hooks) -> None:
+        """AuditLoopHooks is structurally compatible — not a subclass.
+
+        This is the discipline guard: AuditLoopHooks must remain free of
+        inheritance from NoOpHooks so the Protocol contract (and not class
+        hierarchy) is what enforces compatibility.
+        """
+        from vds_agent_core.agents.hooks import NoOpHooks
+
+        assert not isinstance(audit_hooks, NoOpHooks)
+
+    def test_all_protocol_methods_are_callable(self, audit_hooks) -> None:
+        """Every Protocol method exists on AuditLoopHooks and is callable."""
+        protocol_methods = (
+            "should_skip_first_step",
+            "is_evidence_recording",
+            "is_context_query",
+            "has_read_activity",
+            "count_doc_reads",
+            "is_doc_search",
+            "lookup_evidence_requirements",
+            "get_trace_context",
+            "get_trace_span_name",
+            "get_service_name",
+        )
+        for name in protocol_methods:
+            method = getattr(audit_hooks, name, None)
+            assert method is not None, f"AuditLoopHooks missing {name}"
+            assert callable(method), f"AuditLoopHooks.{name} not callable"
+
+
+class TestAuditSpecificReturnValues:
+    """Calling AuditLoopHooks methods returns audit-specific values."""
+
+    def test_get_service_name_returns_audit_identifier(self, audit_hooks) -> None:
+        """AuditLoopHooks must report the audit OTel service.name."""
+        assert audit_hooks.get_service_name() == "vds-audit-orchestrator"
+
+    def test_get_trace_span_name_uses_audit_prefix(self, audit_hooks) -> None:
+        """Span name format is ``audit.loop.step{N}.{tool}``."""
+        name = audit_hooks.get_trace_span_name(step=3, tool="search_docs")
+        assert name == "audit.loop.step3.search_docs"
+
+    def test_get_trace_context_returns_empty_dict(self, audit_hooks) -> None:
+        """AuditLoopHooks delegates audit-context propagation to
+        ``audit_otel_span`` in logging_config and returns {} from this hook."""
+        ctx = audit_hooks.get_trace_context()
+        assert ctx == {}
+        assert isinstance(ctx, dict)
+
+    def test_should_skip_first_step_for_get_row_context(self, audit_hooks) -> None:
+        """should_skip_first_step returns True for GET_ROW_CONTEXT tool."""
+        from vds_audit_orchestrator.agents.tool_registry import ToolName
+
+        assert audit_hooks.should_skip_first_step(tool=ToolName.GET_ROW_CONTEXT, context={}) is True
+
+    def test_is_evidence_recording_for_record_evidence_refs(self, audit_hooks) -> None:
+        """is_evidence_recording returns True for RECORD_EVIDENCE_REFS."""
+        from vds_audit_orchestrator.agents.tool_registry import ToolName
+
+        assert audit_hooks.is_evidence_recording(ToolName.RECORD_EVIDENCE_REFS) is True
+        # And False for an arbitrary other tool name.
+        assert audit_hooks.is_evidence_recording("not_a_tool") is False
+
+    def test_lookup_evidence_requirements_returns_dict(self, audit_hooks) -> None:
+        """lookup_evidence_requirements always returns a dict (never None)."""
+        result = audit_hooks.lookup_evidence_requirements({})
+        assert isinstance(result, dict)
+        # Defaults must include is_default flag per Protocol contract.
+        if result:
+            assert "is_default" in result
+
+
+class TestProtocolSubstitutability:
+    """AuditLoopHooks can be used wherever LoopBehaviorHooks is expected."""
+
+    def test_audit_hooks_substitute_for_protocol_consumer(self, audit_hooks) -> None:
+        """A function annotated with LoopBehaviorHooks accepts AuditLoopHooks."""
+        from vds_agent_core.agents.hooks import LoopBehaviorHooks
+
+        def consumer(hooks: LoopBehaviorHooks) -> str:
+            # Exercise multiple Protocol methods to prove duck-typing works.
+            assert isinstance(hooks, LoopBehaviorHooks)
+            return hooks.get_service_name()
+
+        result = consumer(audit_hooks)
+        assert result == "vds-audit-orchestrator"
+
+    def test_noop_and_audit_hooks_both_satisfy_protocol(self, audit_hooks) -> None:
+        """Both built-in NoOpHooks and AuditLoopHooks satisfy the Protocol."""
+        from vds_agent_core.agents.hooks import LoopBehaviorHooks, NoOpHooks
+
+        noop = NoOpHooks()
+        assert isinstance(noop, LoopBehaviorHooks)
+        assert isinstance(audit_hooks, LoopBehaviorHooks)
+        # Distinct service names verify they are genuinely different impls.
+        assert noop.get_service_name() != audit_hooks.get_service_name()

package/skills/vds-skill/vds-scripts/vds_agent_core/tests/integration/test_audit_observability_integration.py

@@ -0,0 +1,246 @@
+"""Cross-orchestrator integration tests for the audit ↔ vds_agent_core
+observability contract (Phase 9d).
+
+These tests assert that ``audit_orchestrator.logging_config.audit_otel_span``
+and ``audit_orchestrator.cli_impl.init_tracing`` correctly delegate to
+``vds_agent_core.observability.AgentTracer`` and that audit-specific
+contextvars (audit_id / repo / check_id / agent / phase / task_id)
+surface as span attributes.
+
+Skipped gracefully when ``vds_audit_orchestrator`` is not installed in the
+current pytest workspace — these are integration tests, not unit tests.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+# Skip the entire module if audit orchestrator is not importable in the
+# current pytest scope (e.g., when running this package in isolation).
+pytest.importorskip(
+    "vds_audit_orchestrator",
+    reason="audit integration tests require vds_audit_orchestrator on PYTHONPATH",
+)
+
+
+@pytest.fixture(autouse=True)
+def _reset_audit_context() -> None:
+    """Ensure each test starts with a clean audit contextvar state."""
+    from vds_audit_orchestrator.logging_config import clear_audit_context
+
+    clear_audit_context()
+    yield
+    clear_audit_context()
+
+
+class TestAuditOtelSpanContract:
+    """audit_otel_span must merge audit contextvars into span attributes."""
+
+    def test_audit_otel_span_yields_span_when_otel_available(self) -> None:
+        """When OpenTelemetry is installed, audit_otel_span yields a real Span object."""
+        from vds_audit_orchestrator.logging_config import audit_otel_span
+
+        with audit_otel_span("test.span", attributes={"k": "v"}) as span:
+            # Either a real Span (OTel installed) or None (no-op fallback).
+            # In our workspace OTel is available; assert we got an object.
+            assert span is None or hasattr(span, "set_attribute")
+
+    def test_audit_contextvars_propagate_to_span_attributes(self) -> None:
+        """audit_id / repo / check_id contextvars must appear on the span."""
+        from vds_audit_orchestrator.logging_config import (
+            audit_otel_span,
+            set_audit_context,
+        )
+
+        set_audit_context(audit_id="aud-42", repo="vds-scripts", check_id="C.1")
+
+        with audit_otel_span("audit.test.span", attributes={"extra": "marker"}) as span:
+            if span is None:
+                pytest.skip("OpenTelemetry not installed in this environment")
+            attrs = dict(span.attributes) if hasattr(span, "attributes") else {}
+            assert attrs.get("audit_id") == "aud-42"
+            assert attrs.get("repo") == "vds-scripts"
+            assert attrs.get("check_id") == "C.1"
+            assert attrs.get("extra") == "marker"
+
+    def test_extra_attributes_override_audit_contextvars(self) -> None:
+        """Extra dict overrides matching contextvar keys."""
+        from vds_audit_orchestrator.logging_config import (
+            audit_otel_span,
+            set_audit_context,
+        )
+
+        set_audit_context(audit_id="aud-A", repo="repo-A")
+
+        with audit_otel_span(
+            "audit.override.span",
+            attributes={"audit_id": "aud-OVERRIDE", "x": "y"},
+        ) as span:
+            if span is None:
+                pytest.skip("OpenTelemetry not installed in this environment")
+            attrs = dict(span.attributes) if hasattr(span, "attributes") else {}
+            # Spec: ``audit_trace_attrs`` overlays ``extra`` last → extra wins.
+            assert attrs.get("audit_id") == "aud-OVERRIDE"
+            assert attrs.get("repo") == "repo-A"
+            assert attrs.get("x") == "y"
+
+    def test_audit_otel_span_without_contextvars_still_works(self) -> None:
+        """audit_otel_span must never raise when no contextvars are set."""
+        from vds_audit_orchestrator.logging_config import audit_otel_span
+
+        # No set_audit_context — all contextvars are None.
+        with audit_otel_span("audit.bare.span") as span:
+            if span is None:
+                return  # OTel not installed → no-op contract honored
+            attrs = dict(span.attributes) if hasattr(span, "attributes") else {}
+            # None-valued contextvars must NOT bleed into attributes.
+            assert "audit_id" not in attrs
+            assert "repo" not in attrs
+
+    def test_audit_otel_span_partial_contextvars(self) -> None:
+        """Only set contextvars surface; unset ones must not appear at all."""
+        from vds_audit_orchestrator.logging_config import (
+            audit_otel_span,
+            set_audit_context,
+        )
+
+        set_audit_context(audit_id="only-this", phase="phase-9d")
+
+        with audit_otel_span("audit.partial.span") as span:
+            if span is None:
+                pytest.skip("OpenTelemetry not installed in this environment")
+            attrs = dict(span.attributes) if hasattr(span, "attributes") else {}
+            assert attrs.get("audit_id") == "only-this"
+            assert attrs.get("phase") == "phase-9d"
+            # Unset contextvars must not pollute the attribute dict.
+            assert "repo" not in attrs
+            assert "check_id" not in attrs
+            assert "task_id" not in attrs
+
+    def test_audit_trace_attrs_pure_data_helper(self) -> None:
+        """audit_trace_attrs returns merged dict without touching tracer."""
+        from vds_audit_orchestrator.logging_config import (
+            audit_trace_attrs,
+            set_audit_context,
+        )
+
+        set_audit_context(
+            audit_id="A1",
+            repo="R1",
+            check_id="C1",
+            agent="alpha",
+            phase="p7",
+            task_id="t9",
+        )
+
+        merged = audit_trace_attrs({"extra": "added"})
+        assert merged["audit_id"] == "A1"
+        assert merged["repo"] == "R1"
+        assert merged["check_id"] == "C1"
+        assert merged["agent"] == "alpha"
+        assert merged["phase"] == "p7"
+        assert merged["task_id"] == "t9"
+        assert merged["extra"] == "added"
+
+
+class TestInitTracingContract:
+    """audit_orchestrator.cli_impl.init_tracing → AgentTracer construction."""
+
+    def test_init_tracing_disabled_is_noop(self) -> None:
+        """init_tracing(enabled=False) must return without instantiating OTel."""
+        from vds_audit_orchestrator.cli_impl import init_tracing
+
+        # Should not raise, should not log, should not set up any provider.
+        result = init_tracing(enabled=False)
+        assert result is None
+
+    def test_init_tracing_constructs_agent_tracer_with_audit_service_name(self) -> None:
+        """init_tracing constructs AgentTracer with the audit service_name."""
+        from unittest.mock import MagicMock, patch
+
+        from vds_audit_orchestrator.cli_impl import init_tracing
+
+        with patch("vds_agent_core.observability.AgentTracer") as MockAgentTracer:
+            mock_instance = MagicMock()
+            mock_instance.is_enabled = False  # short-circuit OTLP wiring
+            MockAgentTracer.return_value = mock_instance
+
+            init_tracing(service_name="vds-audit-orchestrator", enabled=True)
+
+            MockAgentTracer.assert_called_once_with(
+                service_name="vds-audit-orchestrator",
+                enabled=True,
+            )
+
+    def test_init_tracing_uses_default_audit_service_name(self) -> None:
+        """The default service_name is the audit-specific identifier."""
+        from unittest.mock import MagicMock, patch
+
+        from vds_audit_orchestrator.cli_impl import init_tracing
+
+        with patch("vds_agent_core.observability.AgentTracer") as MockAgentTracer:
+            mock_instance = MagicMock()
+            mock_instance.is_enabled = False
+            MockAgentTracer.return_value = mock_instance
+
+            init_tracing(enabled=True)
+
+            _, kwargs = MockAgentTracer.call_args
+            assert kwargs.get("service_name") == "vds-audit-orchestrator"
+
+    def test_init_tracing_skips_otlp_when_no_endpoint(self) -> None:
+        """No OTLP exporter is wired when endpoint=None."""
+        from unittest.mock import MagicMock, patch
+
+        from vds_audit_orchestrator.cli_impl import init_tracing
+
+        with patch("vds_agent_core.observability.AgentTracer") as MockAgentTracer:
+            mock_instance = MagicMock()
+            mock_instance.is_enabled = True
+            MockAgentTracer.return_value = mock_instance
+
+            # No endpoint → must not import OTLP exporter modules.
+            init_tracing(endpoint=None, enabled=True)
+
+            # The tracer is constructed but no add_span_processor call should
+            # have happened on the mock (we never reach OTLP block).
+            mock_instance.add_span_processor.assert_not_called()
+
+
+class TestSpanCorrelationContract:
+    """End-to-end: audit_otel_span uses the same singleton AgentTracer."""
+
+    def test_singleton_tracer_reused_across_spans(self) -> None:
+        """The first span lazily creates the audit AgentTracer, subsequent
+        calls reuse it (the module-level singleton)."""
+        from vds_audit_orchestrator import logging_config
+        from vds_audit_orchestrator.logging_config import audit_otel_span
+
+        # Reset singleton before this test (keeps it independent of order).
+        logging_config._AUDIT_TRACER = None
+
+        with audit_otel_span("first.span"):
+            pass
+
+        first = logging_config._AUDIT_TRACER
+        assert first is not None
+
+        with audit_otel_span("second.span"):
+            pass
+
+        # Same tracer instance → no per-call provider re-init.
+        assert logging_config._AUDIT_TRACER is first
+
+    def test_audit_tracer_service_name_is_audit_specific(self) -> None:
+        """The lazy singleton tracer is constructed with the audit service name."""
+        from vds_audit_orchestrator import logging_config
+        from vds_audit_orchestrator.logging_config import audit_otel_span
+
+        logging_config._AUDIT_TRACER = None
+
+        with audit_otel_span("svc-name-check"):
+            pass
+
+        tracer = logging_config._AUDIT_TRACER
+        assert tracer is not None
+        assert tracer.service_name == "vds-audit-orchestrator"

package/skills/vds-skill/vds-scripts/vds_agent_core/tests/integration/test_public_api_stability.py

@@ -0,0 +1,91 @@
+"""Public API stability tests for vds_agent_core (Phase 10 Contract update).
+
+These tests pin the public surface that other orchestrators (most notably
+``vds_audit_orchestrator``) depend on. Any backwards-incompatible change to
+these contracts must explicitly update this file — the failing test makes
+the breakage visible at the call site that ships first.
+
+Contracts pinned:
+
+1. ``AgentTracer.open_span(name, attributes)`` is callable and yields a
+   ``Span | None`` (concrete object when OTel is available, None otherwise).
+
+This file is integration-tier (it touches the public boundary across
+multiple subpackages) but does NOT depend on ``vds_audit_orchestrator``.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+# ---------------------------------------------------------------------------
+# Contract 3.1 — AgentTracer.open_span signature & return type
+# ---------------------------------------------------------------------------
+
+
+class TestAgentTracerOpenSpanContract:
+    """AgentTracer.open_span must remain backwards-compatible."""
+
+    def test_open_span_signature_accepts_name_and_attributes(self) -> None:
+        from vds_agent_core.observability import AgentTracer
+
+        sig = inspect.signature(AgentTracer.open_span)
+        params = list(sig.parameters.values())
+        # self, name, attributes
+        assert len(params) >= 3
+        assert params[1].name == "name"
+        assert params[2].name == "attributes"
+
+    def test_open_span_attributes_is_optional(self) -> None:
+        """``attributes`` must default to None so callers can omit it."""
+        from vds_agent_core.observability import AgentTracer
+
+        sig = inspect.signature(AgentTracer.open_span)
+        attrs_param = sig.parameters["attributes"]
+        assert attrs_param.default is None
+
+    def test_open_span_yields_span_or_none(self) -> None:
+        """Context manager yields either a Span-like object or None."""
+        from vds_agent_core.observability import AgentTracer
+
+        tracer = AgentTracer(service_name="api-stability", enabled=True)
+        with tracer.open_span("api.test", attributes={"k": "v"}) as span:
+            assert span is None or hasattr(span, "set_attribute")
+
+    def test_open_span_yields_none_when_disabled(self) -> None:
+        """Disabled tracer yields None — call site can branch on truthiness."""
+        from vds_agent_core.observability import AgentTracer
+
+        tracer = AgentTracer(service_name="api-stability", enabled=False)
+        with tracer.open_span("disabled.test") as span:
+            assert span is None
+
+    def test_open_span_handles_no_attributes(self) -> None:
+        """open_span(name) without attributes is the expected minimum call."""
+        from vds_agent_core.observability import AgentTracer
+
+        tracer = AgentTracer(service_name="api-stability", enabled=True)
+        with tracer.open_span("minimal") as span:
+            assert span is None or hasattr(span, "set_attribute")
+
+
+# ---------------------------------------------------------------------------
+# Public API surface — module-level exports must remain stable
+# ---------------------------------------------------------------------------
+
+
+class TestPublicApiSurface:
+    """Re-exports from package __init__ files form the documented contract."""
+
+    def test_observability_public_exports(self) -> None:
+        import vds_agent_core.observability as obs
+
+        assert "AgentTracer" in obs.__all__
+        assert hasattr(obs, "AgentTracer")
+
+    def test_agents_public_exports(self) -> None:
+        import vds_agent_core.agents as ag
+
+        for name in ("LoopBehaviorHooks", "NoOpHooks"):
+            assert name in ag.__all__, f"{name} missing from agents.__all__"
+            assert hasattr(ag, name), f"{name} not exported from agents"

package/skills/vds-skill/vds-scripts/vds_agent_core/tests/unit/llm/test_call_site_parallelism.py

@@ -0,0 +1,30 @@
+"""Verify EmbeddingClient mirrors LLMClient call-site shape (NFR-225.6)."""
+
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings
+from vds_agent_core.llm.embedding import EmbeddingClient, EmbeddingSettings
+from vds_agent_core.llm.provider import LLMClient, LLMSettings
+
+
+def test_protocol_methods_parallel() -> None:
+    """LLMClient and EmbeddingClient share the same call-site shape."""
+    assert hasattr(LLMClient, "chat")
+    assert hasattr(EmbeddingClient, "embed")
+    assert hasattr(EmbeddingClient, "embed_batch")
+    assert hasattr(EmbeddingClient, "estimate_cost")
+    assert hasattr(EmbeddingClient, "aclose")
+
+
+def test_settings_subclass_basesettings() -> None:
+    """Both Settings classes inherit BaseSettings (env-var driven)."""
+    assert issubclass(LLMSettings, BaseSettings)
+    assert issubclass(EmbeddingSettings, BaseSettings)
+
+
+def test_settings_have_factory_and_select_model() -> None:
+    """Both expose `build_client()` + `select_model()` for parity."""
+    assert hasattr(LLMSettings, "build_client")
+    assert hasattr(LLMSettings, "select_model")
+    assert hasattr(EmbeddingSettings, "build_client")
+    assert hasattr(EmbeddingSettings, "select_model")