@ngocsangairvds/vsaf 4.1.9 → 4.1.10

package/skills/vds-skill/runtime/vds_agent_core/docs/embedding.md

@@ -0,0 +1,468 @@
+# VDS AI Memory: Pluggable Embedding (Phase 225)
+
+> Operator + developer guide for the Phase 225 pluggable embedding SDK.
+> Authoritative spec: `.gpt-5.4/specs/vds-ai-memory/` v20.6.1.
+> Architectural decisions: ADR-98 (Ollama default on Metal GPU),
+> ADR-99 (Generic provider registry), ADR-100 (3-layer cascade settings).
+
+This guide answers operator-facing "How do I..." questions for the embedding
+subsystem introduced in Phase 225. The embedding SDK lives in
+`vds_agent_core.llm.embedding` and is the single canonical surface across all
+orchestrators (memory, audit, progress_report, evolution).
+
+---
+
+## Quick start
+
+The minimum operator config to switch the production embedding provider:
+
+```bash
+# ~/.vds/.env  (operator-private, NOT in this repo)
+VDS_AGENT_CORE_EMBED__PROVIDER=ollama
+VDS_AGENT_CORE_EMBED__BASE_URL=http://host.docker.internal:11434
+VDS_AGENT_CORE_EMBED__MODEL_STANDARD=bge-m3
+```
+
+Three env vars are enough for the default Ollama path. Cloud providers add an
+`API_KEY` (see playbook below).
+
+---
+
+## Call-site parallelism
+
+The chat-LLM and embedding SDKs use the same idiom — `settings.build_client()`
++ `select_model("standard")`. The operator-facing knobs mirror each other:
+
+| Concern | Chat LLM (`vds_agent_core.llm.provider`) | Embedding (`vds_agent_core.llm.embedding`) |
+|---|---|---|
+| Settings class | `LLMSettings` | `EmbeddingSettings` |
+| Env prefix | `VDS_AGENT_CORE_LLM__` | `VDS_AGENT_CORE_EMBED__` |
+| Model tier selector | `select_model("standard")` | `select_model("standard")` |
+| Builder | `settings.build_client()` | `settings.build_client()` |
+| Per-agent cascade | `LLMSettings.for_agent(...)` | `EmbeddingSettings.for_agent(...)` |
+| Async lifetime | `await client.aclose()` | `await client.aclose()` |
+
+```python
+from vds_agent_core.llm.embedding import EmbeddingSettings
+from vds_agent_core.llm.provider import LLMSettings
+
+# Chat completions
+llm = LLMSettings()
+chat = llm.build_client()
+reply = await chat.complete("hi", model=llm.select_model("standard"))
+
+# Embeddings — identical idiom
+emb = EmbeddingSettings()
+client = emb.build_client()
+vector = await client.embed("hi", model=emb.select_model("standard"))
+
+await chat.aclose()
+await client.aclose()
+```
+
+The two clients are independent; you can mix providers freely (e.g. chat via
+OpenAI, embeddings via local Ollama).
+
+---
+
+## Provider switching matrix
+
+The same four env vars switch every supported provider. Pick a row, paste it
+into `~/.vds/.env`, restart memory orchestrator.
+
+| Provider | `PROVIDER` | `BASE_URL` | `MODEL_STANDARD` | Default `DIMENSION` |
+|---|---|---|---|---|
+| Ollama (default, local) | `ollama` | `http://host.docker.internal:11434` | `bge-m3` | 1024 |
+| OpenAI | `openai` | `https://api.openai.com/v1` | `text-embedding-3-small` | 1536 |
+| OpenAI (matryoshka) | `openai` | `https://api.openai.com/v1` | `text-embedding-3-large` | 1024 or 3072 |
+| Cohere | `cohere` | `https://api.cohere.ai/v1` | `embed-english-v3.0` | 1024 |
+| Voyage | `voyage` | `https://api.voyageai.com/v1` | `voyage-3` | 1024 |
+| Mistral | `mistral` | `https://api.mistral.ai/v1` | `mistral-embed` | 1024 |
+| Jina | `jina` | `https://api.jina.ai/v1` | `jina-embeddings-v3` | 1024 |
+| Local sentence-transformers | `local` | _(unused)_ | `BAAI/bge-m3` | 1024 |
+| Hash (deterministic test) | `hash` | _(unused)_ | _(any)_ | 1024 |
+| Self-hosted bge-m3 (Ollama) | `ollama` | `http://your-host:11434` | `bge-m3` | 1024 |
+
+Cloud providers also need an API key — supplied via `..._EMBED__API_KEY` in
+`~/.vds/.env`, or via the credential-reference indirection
+(`${env:OPENAI_API_KEY}`) in a profile YAML (see Track-B section below).
+
+---
+
+## Dimension constraints
+
+Qdrant collections are created with a fixed dimension at first deploy. After
+that, dimension is immutable for the life of the collection. Phase 225
+enforces three validator invariants in `EmbeddingRuntimeConfig` to catch
+mismatches at startup, before any vector hits the index.
+
+### The 1024 baseline
+
+Ollama `bge-m3` (the default) emits 1024-dim vectors. Most non-OpenAI cloud
+providers also default to 1024, so 1024 is the de-facto VDS baseline. Switching
+to a different-dimensional model requires a Qdrant collection rebuild — see
+"Switching to a different-dimensional cloud model" below.
+
+### OpenAI matryoshka
+
+`text-embedding-3-large` supports matryoshka truncation: the model is trained
+so the first N dimensions of its 3072-dim output are usable as a smaller
+embedding. So `dimension=1024` truncates the 3072-dim output and stays
+compatible with the Qdrant 1024 baseline.
+
+`text-embedding-3-small` does NOT support truncation; its native dim is 1536
+and it must be used at 1536.
+
+### The three validator invariants (FR-225.16)
+
+1. **(a) Dim stability vs live Qdrant collection** — at startup, if
+   `verify_dim_against_qdrant=true` (default), a probe checks the live
+   collection dim and fails fast on mismatch.
+2. **(b) OpenAI matryoshka safety** — `text-embedding-3-small` + dim != 1536
+   raises `ConfigError`.
+3. **(c) First-deploy guard** — the requested dim must be either the
+   provider default (e.g. 1536 for openai) OR 1024 (the VDS baseline). Any
+   other value fails fast.
+
+```python
+from vds_agent_core.llm.embedding import EmbeddingSettings, ConfigError
+
+# This raises ConfigError: 3072 is neither openai default (1536) nor 1024
+EmbeddingSettings(provider="openai", model_standard="text-embedding-3-large", dimension=3072)
+```
+
+---
+
+## Cloud-failover playbook
+
+Addresses R-225.1: Linux deploy targets without Ollama on the host.
+
+When the local Ollama host is unavailable (e.g. the production Linux host
+lacks Metal GPU or has Ollama disabled), switch the orchestrator to OpenAI:
+
+1. Provision an OpenAI API key with embedding access.
+2. Add to `~/.vds/.env`:
+   ```bash
+   VDS_AGENT_CORE_EMBED__PROVIDER=openai
+   VDS_AGENT_CORE_EMBED__BASE_URL=https://api.openai.com/v1
+   VDS_AGENT_CORE_EMBED__API_KEY=sk-...                 # provider key
+   VDS_AGENT_CORE_EMBED__MODEL_STANDARD=text-embedding-3-large
+   VDS_AGENT_CORE_EMBED__DIMENSION=1024                 # matryoshka → 1024
+   ```
+3. Restart memory orchestrator. The validator (b) accepts
+   `text-embedding-3-large@1024` (matryoshka). The Qdrant collection at the
+   1024 baseline is reusable as-is — no rebuild needed.
+4. Confirm via `vds-cli doctor` — the embedding-health probe must pass.
+
+If the deploy uses a different dim (e.g. native 1536 with `-small`), follow the
+collection-rebuild playbook in the next section.
+
+---
+
+## Per-orchestrator subclass pattern
+
+Some orchestrators (audit, progress_report, evolution) need their OWN
+embedding settings — distinct env namespace, distinct override surface — so
+they don't stomp on `VDS_AGENT_CORE_EMBED__*` shared keys.
+
+The pattern (NFR-225.6 / NFR-225.7 / FR-225.9): subclass `EmbeddingSettings`
+and override `model_config` with a custom env_prefix.
+
+```python
+from pydantic_settings import SettingsConfigDict
+from vds_agent_core.config import VDS_BASE_SETTINGS_CONFIG
+from vds_agent_core.llm.embedding import EmbeddingSettings
+
+class AuditEmbeddingSettings(EmbeddingSettings):
+    """Audit orchestrator embedding settings — own env namespace."""
+
+    model_config = SettingsConfigDict(  # type: ignore[typeddict-unknown-key]
+        env_prefix="VDS_AUDIT_EMBED__",
+        **VDS_BASE_SETTINGS_CONFIG,
+    )
+```
+
+The subclass inherits all validator invariants, `build_client()`, the registry
+lookup, and `for_agent()`. Operators read from `VDS_AUDIT_EMBED__*` instead of
+the shared core prefix; that means the audit orchestrator can run a different
+provider than memory_orchestrator on the same host.
+
+---
+
+## Per-agent provider config (Track-B)
+
+Phase 225 Track-B introduces per-agent provider configuration via a 3-layer
+cascade resolved by `EmbeddingSettings.for_agent(agent_id, ...)`. The same
+mechanism applies to `LLMSettings.for_agent(...)`.
+
+### The 3-layer cascade
+
+```text
++--------------------------------------------------------+
+| Layer 1: programmatic overrides   (highest precedence) |
+|   passed via for_agent(overrides={...})                |
++--------------------------------------------------------+
+| Layer 2: API settings (Path B)                         |
+|   api_settings.embedding_settings dict                 |
++--------------------------------------------------------+
+| Layer 3: env vars (Path A)                             |
+|   VDS_AGENT_<AGENT_ID>_EMBED__*                        |
++--------------------------------------------------------+
+| Layer 4: defaults                                      |
+|   profile YAML / class defaults                        |
++--------------------------------------------------------+
+```
+
+### Three resolution paths
+
+- **Path A (env)** — `VDS_AGENT_<SANITIZED_AGENT_ID>_EMBED__PROVIDER=ollama` etc.
+  Sanitized = uppercase, non-alphanumeric → `_`.
+- **Path B (API)** — `api_settings.embedding_settings` dict, fetched from
+  Postgres `vds_ai_memory.api_settings` (or any `BaseSettings`-compatible
+  source). Wins on conflict over Path A.
+- **Path C (programmatic)** — `for_agent(overrides={"provider": "..."})`
+  forced at call time, highest precedence.
+
+### Credential-reference indirection
+
+Profile YAML and API rows MUST NEVER carry raw API keys. Instead, use
+`${env:VAR_NAME}` references that resolve at runtime against the process env:
+
+```yaml
+# vds_agent_core/profiles/agent_audit.yaml
+embedding:
+  provider: openai
+  base_url: https://api.openai.com/v1
+  api_key: ${env:OPENAI_API_KEY}     # resolved at load
+  model_standard: text-embedding-3-large
+  dimension: 1024
+```
+
+A boot-time allowlist (`VDS_AGENT_CORE__ALLOWED_ENV_REFS`) restricts which
+env vars may be referenced; unlisted refs fail closed (FR-226.7).
+
+---
+
+## Switching to a different-dimensional cloud model
+
+Use this playbook ONLY when changing the Qdrant collection dimension is
+unavoidable (e.g. you must use OpenAI native 1536 dim).
+
+1. Stop the memory orchestrator: `docker compose stop memory_orchestrator`.
+2. Drop the existing Qdrant collection:
+   ```bash
+   ./scripts/worktree_uv.sh run --project vds_cli vds-cli memory \
+       admin drop-collection --collection vds_memories --confirm
+   ```
+3. Update `~/.vds/.env` to the new model + dim:
+   ```bash
+   VDS_AGENT_CORE_EMBED__PROVIDER=openai
+   VDS_AGENT_CORE_EMBED__MODEL_STANDARD=text-embedding-3-small
+   VDS_AGENT_CORE_EMBED__DIMENSION=1536
+   ```
+4. Recreate the collection at the new dim (memory orchestrator does this
+   automatically on first boot if the collection is absent).
+5. Re-embed all memories from the source rows in Postgres:
+   ```bash
+   ./scripts/worktree_uv.sh run --project vds_cli vds-cli memory \
+       admin reindex --batch-size 100
+   ```
+6. Validate with a sanity query and `vds-cli doctor`.
+
+This is destructive — every cached vector is recomputed. Plan for the
+re-embedding cost (token cost * memory count for cloud providers).
+
+---
+
+## Disabling dimension verification
+
+`EMBEDDING_VERIFY_DIM_AGAINST_QDRANT=false` skips invariant (a). This is
+**unsupported in production**. Switching embedding models without dim
+verification can silently corrupt the Qdrant collection (writes succeed but
+queries return garbage cosine scores).
+
+When set to false, the SDK emits a one-shot startup WARN
+(`dimension_verification_disabled`). NFR-225.11: **Phase 228 DELIVERED 2026-05-03**
+— `vds-cli doctor` now surfaces this as a WARN row via `_doctor_check_embedding()`,
+and `/api/v1/health/full` exposes embedding sub-layer with reachability probe.
+(was documentation-promised; now implementation-delivered).
+
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli doctor
+# WARN: VDS_AGENT_CORE_EMBED__VERIFY_DIM_AGAINST_QDRANT=false
+#       Dimension verification is disabled — see docs/embedding.md.
+```
+
+---
+
+## Adding a new provider (3-step recipe)
+
+NFR-225.9 drop-in extensibility. To wire in (say) Cohere v4 as a distinct
+provider without modifying core source files:
+
+```python
+# 1. Implement a client (or reuse OpenAIEmbeddingClient if API-shape matches)
+from vds_agent_core.llm.embedding import (
+    EMBEDDING_PROVIDERS, PROVIDER_DEFAULTS, OpenAIEmbeddingClient,
+)
+
+class CohereV4EmbeddingClient(OpenAIEmbeddingClient):
+    @classmethod
+    def from_settings(cls, config):
+        return cls(config, provider_name="cohere-v4")
+
+# 2. Register in EMBEDDING_PROVIDERS
+EMBEDDING_PROVIDERS["cohere-v4"] = CohereV4EmbeddingClient.from_settings
+
+# 3. Add provider defaults
+PROVIDER_DEFAULTS["cohere-v4"] = {
+    "model": "embed-english-v4.0",
+    "dimension": 1024,
+    "base_url": "https://api.cohere.ai/v2",
+}
+```
+
+After registration, set `VDS_AGENT_CORE_EMBED__PROVIDER=cohere-v4` in
+`~/.vds/.env`. Three lines of code change in your project; no patches to
+`vds_agent_core` source needed.
+
+For collision protection, prefer `register_provider("cohere-v4", factory)`
+which raises `ConfigError` on name collisions unless `force=True`.
+
+---
+
+## Recommended `~/.vds/.env`
+
+The canonical Phase 225 env block (operator-private file, NOT in this repo).
+Legacy `EMBEDDING_*` env vars continue to work for one cycle for back-compat;
+they should be migrated to the canonical names below.
+
+```bash
+# Phase 225 — canonical embedding env vars
+VDS_AGENT_CORE_EMBED__PROVIDER=ollama
+VDS_AGENT_CORE_EMBED__BASE_URL=http://host.docker.internal:11434
+VDS_AGENT_CORE_EMBED__MODEL_STANDARD=bge-m3
+VDS_AGENT_CORE_EMBED__MODEL_SIMPLE=bge-m3
+VDS_AGENT_CORE_EMBED__MODEL_COMPLEX=bge-m3
+VDS_AGENT_CORE_EMBED__DIMENSION=1024
+VDS_AGENT_CORE_EMBED__TIMEOUT_SECONDS=30
+VDS_AGENT_CORE_EMBED__FAIL_OPEN=false
+VDS_AGENT_CORE_EMBED__VERIFY_DIM_AGAINST_QDRANT=true
+
+# Cloud-failover (uncomment to activate)
+# VDS_AGENT_CORE_EMBED__PROVIDER=openai
+# VDS_AGENT_CORE_EMBED__BASE_URL=https://api.openai.com/v1
+# VDS_AGENT_CORE_EMBED__API_KEY=sk-...
+# VDS_AGENT_CORE_EMBED__MODEL_STANDARD=text-embedding-3-large
+# VDS_AGENT_CORE_EMBED__DIMENSION=1024
+
+# Per-agent override example (audit orchestrator uses its own prefix subclass)
+# VDS_AUDIT_EMBED__PROVIDER=ollama
+# VDS_AUDIT_EMBED__MODEL_STANDARD=bge-m3
+```
+
+Legacy back-compat (deprecated, removed next cycle):
+
+```bash
+# Old names — still honored for one cycle
+EMBEDDING_PROVIDER=ollama                 # → VDS_AGENT_CORE_EMBED__PROVIDER
+EMBEDDING_BASE_URL=...                    # → VDS_AGENT_CORE_EMBED__BASE_URL
+EMBEDDING_MODEL=bge-m3                    # → ..._MODEL_STANDARD
+```
+
+---
+
+## Structured Log Events (W7+W8 Deferred Sections)
+
+The embedding SDK emits structured log events via `structlog` for operator observability.
+All events are routable via `VDS_AGENT_CORE__LOG_RESOLUTION=true` (one log per agent_id + kind).
+
+### Health Check & Fallback Events
+
+| Event Key | Severity | Trigger | Action |
+|-----------|----------|---------|--------|
+| `embedding_health_check_failed_fatal` | ERROR | Health-check probe timeout or permanent service unreachable | Startup fails; operator must resolve provider connectivity or change config |
+| `embedding_health_check_failed_fallback_to_hash` | WARN | Health-check fails but `FAIL_OPEN=true` | Falls back to deterministic hash embeddings; production not recommended |
+| `dimension_verification_disabled` | WARN | `VERIFY_DIM_AGAINST_QDRANT=false` at startup | Operator MUST ensure new vectors match collection dimension (silent corruption risk) |
+
+### Provider & Model Resolution Events
+
+| Event Key | Severity | Trigger | Action |
+|-----------|----------|---------|--------|
+| `provider_model_mismatch` | WARN | `PROVIDER=X` set + `MODEL_STANDARD=Y/model` parses to different provider | Explicit provider takes precedence; WARN clarifies the override |
+| `for_agent_resolved` | INFO | Per-agent cascading resolution completes (Layer 1/2/3 precedence applied) | Logs winner (env / API / programmatic) for audit trail |
+| `for_agent_path_conflict` | WARN | Layer B (API) differs from Layer A (env) at resolution time | Both values logged; Layer B wins; signals operator may have stale Redis state |
+| `profile_embedding_resolved` | INFO | Subclass (e.g., `AuditEmbeddingSettings`) loads YAML profile with credential-ref indirection | `${env:VAR}` references logged after substitution (API key redacted) |
+
+### HTTP & Provider-Specific Events
+
+| Event Key | Severity | Trigger | Action |
+|-----------|----------|---------|--------|
+| `ollama_embed_http_error` | ERROR | HTTP error from Ollama `/api/embed` endpoint | Operator checks Ollama container logs + network connectivity |
+| `ollama_embed_request_error` | ERROR | Ollama request-body validation or timeout | Operator reviews model name + dimension in Ollama config |
+| `ollama_embed_batch_http_error` | ERROR | HTTP error from Ollama batch `/api/embed` (multi-doc) | Same as single-doc; batch retried individually |
+| `ollama_embed_batch_request_error` | ERROR | Request validation on batch (one doc fails, others may pass) | Batch partially replayed via DLQ; operator reviews per-doc payloads |
+| `openai_compat_embed_http_error` | ERROR | HTTP error from OpenAI-compatible provider (Cohere, Voyage, Mistral, Jina) | Operator checks provider status page + API quota |
+| `openai_compat_embed_request_error` | ERROR | Request-body validation or timeout on OpenAI-compat provider | Operator reviews model name + dimension constraints for provider |
+
+---
+
+## Mem0 Cross-Service Embedding Architecture (W8 Deferred)
+
+**CRITICAL OPERATIONAL NOTE**: Phase 225 embedding introduces TWO independent embedding paths. Operators must configure BOTH when switching providers.
+
+### Path 1: vds_agent_core Embedding (New, Phase 225)
+
+- **Config namespace**: `VDS_AGENT_CORE_EMBED__*`
+- **Entry point**: `vds_agent_core.llm.embedding.EmbeddingSettings.build_client()`
+- **Orchestrators using this path**: memory_orchestrator, audit_orchestrator, progress_report_orchestrator, evolution_orchestrator, multi_agent_orchestrator
+- **Control surface**: All 9 providers (Ollama, OpenAI, Cohere, Voyage, Mistral, Jina, LiteLLM, local, hash)
+
+### Path 2: Mem0 Self-Hosted Embedder (Legacy, Coexists)
+
+- **Config namespace**: `MEM0_*` (separate from `VDS_AGENT_CORE_EMBED__*`)
+- **Entry point**: `mem0_orchestrator/services/embedding_adapter.py:231` (Qdrant local embedder or cloud if configured)
+- **Behavior**: Mem0 cloud manages embeddings server-side; self-hosted Mem0 uses its own LLM provider config
+- **When active**: Only when `mem0_orchestrator` is the active memory backend OR mem0 cloud mode is enabled
+
+### Provider Switching Checklist
+
+When operators change the embedding provider, they MUST update:
+
+1. **vds_agent_core path** (ALL orchestrators using memory):
+   ```bash
+   # Edit ~/.vds/.env
+   VDS_AGENT_CORE_EMBED__PROVIDER=openai
+   VDS_AGENT_CORE_EMBED__BASE_URL=https://api.openai.com/v1
+   VDS_AGENT_CORE_EMBED__API_KEY=sk-...
+   VDS_AGENT_CORE_EMBED__MODEL_STANDARD=text-embedding-3-large
+   VDS_AGENT_CORE_EMBED__DIMENSION=1024
+   ```
+
+2. **Mem0 self-hosted path** (if `memory_orchestrator` uses mem0 local embedder):
+   ```bash
+   # Edit ~/.vds/.env or mem0_orchestrator/.env
+   MEM0_EMBEDDING_PROVIDER=ollama  # or openai, cohere, etc.
+   MEM0_EMBEDDING_BASE_URL=...
+   MEM0_EMBEDDING_MODEL=...
+   # See mem0_orchestrator/config.py for full MEM0_* namespace
+   ```
+
+3. **Mem0 cloud** (if using mem0 cloud mode):
+   - No local config needed; mem0 cloud handles embeddings server-side
+   - Verify `MEM0_CONFIG_API_KEY` points to your cloud account
+
+**Consequence of missing either update**: Silent dimension mismatch or failed embedding calls. Always verify both paths after provider changes via `vds-cli doctor` (checks vds_agent_core path) + mem0 health probes (checks mem0 path).
+
+---
+
+## See also
+
+- ADR-98 (Ollama default on Metal GPU) — `.gpt-5.4/specs/vds-ai-memory/design.md`
+- ADR-99 (Generic provider registry) — same file
+- ADR-100 (3-layer cascade settings) — same file
+- FR-225.* (Track-A SDK foundation) — `.gpt-5.4/specs/vds-ai-memory/requirements.md`
+- FR-226.* (Track-B per-agent cascade) — same file (audit-trail prefix preserved)
+- Source: `vds_agent_core/src/vds_agent_core/llm/embedding.py`
+- Tests: `vds_agent_core/tests/unit/llm/`
+- Memory orchestrator integration: `memory_orchestrator/src/vds_memory_orchestrator/service/services/embedding_service.py`

package/skills/vds-skill/runtime/vds_agent_core/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "vds-agent-core"
+version = "0.10.0"
+description = "VDS shared agent infrastructure — LLM, config, skills, agentic loop"
+requires-python = ">=3.13"
+dependencies = [
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.3.0",
+    "structlog>=25.5.0",
+    "httpx>=0.28.1",
+    "pydantic-ai>=1.63.0",
+    "vds-cli-common",
+    "pyyaml>=6.0",  # profiles.py YAML loading
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-timeout>=2.3",
+    "pytest-mock>=3.14",
+]
+litellm = ["litellm>=1.0"]  # Wave 2 (TSK-W2.1)
+langgraph = ["langgraph>=1.0.9", "langgraph-checkpoint>=4.0.0"]
+# vds-scheduler v0.2.0 (ADR-DCP-1):
+# `workflows` extra brings in the DBOS + LangGraph runtime needed by
+# `vds_agent_core.workflows.langgraph_runner` (relocated from scheduler).
+# Audit and scheduler orchestrators install with [workflows].
+workflows = [
+    "dbos>=2.19.0,<3",
+    "langgraph>=1.1.9,<2",
+    "langgraph-checkpoint>=4.0.2,<5",
+]
+dspy = ["dspy-ai>=3.1.3"]
+cohere = ["cohere>=5.0"]
+voyage = ["voyageai>=0.2"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv.sources]
+vds-cli-common = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vds_agent_core"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+timeout = 60

package/skills/vds-skill/runtime/vds_agent_core/src/vds_agent_core/__init__.py

@@ -0,0 +1,29 @@
+"""VDS Agent Core — shared LLM, config, skills, and agentic infrastructure."""
+
+from vds_agent_core.observability import (
+    AgentTracer,
+    BudgetEvent,
+    BudgetEventType,
+    TokenUsage,
+    TraceSpanType,
+    trace_audit,
+    trace_llm_call,
+    trace_span,
+)
+from vds_agent_core.profiles import DEFAULT_RUNTIME_PROFILES_FILE, CodexCredentialResolver
+
+__version__ = "0.10.0"
+
+__all__ = [
+    "DEFAULT_RUNTIME_PROFILES_FILE",
+    "AgentTracer",
+    "BudgetEvent",
+    "BudgetEventType",
+    "CodexCredentialResolver",
+    "TokenUsage",
+    "TraceSpanType",
+    "__version__",
+    "trace_audit",
+    "trace_llm_call",
+    "trace_span",
+]

package/skills/vds-skill/runtime/vds_agent_core/src/vds_agent_core/agents/__init__.py

@@ -0,0 +1,26 @@
+"""Agent primitives — tool registry contract, bounded loop, behavior hooks."""
+
+from vds_agent_core.agents.hooks import LoopBehaviorHooks, NoOpHooks
+from vds_agent_core.agents.loop import (
+    AgentLoopAction,
+    AgentLoopConfig,
+    AgentLoopResult,
+    AgentLoopStep,
+    BoundedAgentLoop,
+    LoopTerminationReason,
+)
+from vds_agent_core.agents.tools import ToolName, ToolRegistry, ToolResponseEnvelope
+
+__all__ = [
+    "AgentLoopAction",
+    "AgentLoopConfig",
+    "AgentLoopResult",
+    "AgentLoopStep",
+    "BoundedAgentLoop",
+    "LoopBehaviorHooks",
+    "LoopTerminationReason",
+    "NoOpHooks",
+    "ToolName",
+    "ToolRegistry",
+    "ToolResponseEnvelope",
+]

package/skills/vds-skill/runtime/vds_agent_core/src/vds_agent_core/agents/hooks.py

@@ -0,0 +1,119 @@
+"""Injectable behavior hooks for BoundedAgentLoop.
+
+The Protocol defines audit-specific branching points that the generic loop
+delegates to.  ``NoOpHooks`` provides neutral defaults so the loop works
+standalone without any orchestrator coupling.
+
+Concrete implementations (e.g. ``AuditLoopHooks``) live in each orchestrator
+package and restore the original branching logic.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class LoopBehaviorHooks(Protocol):
+    """Injectable hooks for orchestrator-specific loop behavior.
+
+    Default implementation (NoOpHooks) does nothing — generic loop behavior.
+    Audit provides AuditLoopHooks with the original branching logic.
+    """
+
+    def should_skip_first_step(self, tool: str, context: dict[str, Any]) -> bool:
+        """Return True if the first step's tool output should be wired into context specially."""
+        ...
+
+    def is_evidence_recording(self, tool: str) -> bool:
+        """Return True if this tool records evidence refs (e.g. RECORD_EVIDENCE_REFS)."""
+        ...
+
+    def is_context_query(self, tool: str) -> bool:
+        """Return True if this tool is a context-fetching query (e.g. GET_ROW_CONTEXT)."""
+        ...
+
+    def has_read_activity(self, trace: list[Any]) -> bool:
+        """Return True if the trace contains concrete read activity (doc/code reads)."""
+        ...
+
+    def count_doc_reads(self, trace: list[Any]) -> int:
+        """Count documentation-related tool steps in the trace."""
+        ...
+
+    def is_doc_search(self, tool: str) -> bool:
+        """Return True if the tool performs documentation search."""
+        ...
+
+    def lookup_evidence_requirements(self, context: dict[str, Any]) -> dict[str, Any]:
+        """Return evidence threshold requirements for the current context.
+
+        Returns a dict with at minimum ``min_evidence_refs`` and
+        ``min_search_patterns`` keys, plus a ``is_default`` flag indicating
+        whether the returned requirements are the generic defaults (True)
+        or orchestrator-specific overrides (False).
+        """
+        ...
+
+    def get_trace_context(self) -> dict[str, Any]:
+        """Return trace context for OpenTelemetry propagation.
+
+        Returns an empty dict when tracing is disabled.
+        Override to return context attributes for active tracing.
+        """
+        return {}
+
+    def get_trace_span_name(self, step: int, tool: str) -> str:
+        """Return the span name for a given loop step.
+
+        Args:
+            step: Step number
+            tool: Tool name being executed
+
+        Default implementation returns "step-N/tool" format.
+        """
+        return f"step-{step}/{tool}"
+
+    def get_service_name(self) -> str:
+        """Return the service name for the tracer resource.
+
+        Default implementation returns "vds-agent-core".
+        """
+        return "vds-agent-core"
+
+
+# --- NoOpHooks implementation -----------------------------------------
+
+
+class NoOpHooks:
+    """Default no-op implementation — all hooks return neutral values."""
+
+    def should_skip_first_step(self, tool: str, context: dict[str, Any]) -> bool:
+        return False
+
+    def is_evidence_recording(self, tool: str) -> bool:
+        return False
+
+    def is_context_query(self, tool: str) -> bool:
+        return False
+
+    def has_read_activity(self, trace: list[Any]) -> bool:
+        return False
+
+    def count_doc_reads(self, trace: list[Any]) -> int:
+        return 0
+
+    def is_doc_search(self, tool: str) -> bool:
+        return False
+
+    def lookup_evidence_requirements(self, context: dict[str, Any]) -> dict[str, Any]:
+        return {"min_evidence_refs": 1, "min_search_patterns": 1, "is_default": True}
+
+    def get_trace_context(self) -> dict[str, Any]:
+        return {}
+
+    def get_trace_span_name(self, step: int, tool: str) -> str:
+        return f"step-{step}/{tool}"
+
+    def get_service_name(self) -> str:
+        return "vds-agent-core"