feat: v1 — boilerplate WxO + web

Boilerplate completo para construir soluciones agénticas sobre IBM
watsonx Orchestrate (ADK 2.x) con una capa web encima.

Destilado de cotemar-poc-n1 y dun-casos-prueba. Incluye:

- 11 docs (best practices, architecture patterns, ADK cheatsheet,
  observability, tool authoring, deployment, RUNBOOK, DEPLOY_TO_NEW_WOX,
  known-issues con 16 errores reales y fix, eval strategy, INDEX)
- 13 templates WxO (orchestrator/specialist/single-meta agents,
  3 connections, KB + runbook, observable_tool decorator, coercion
  helpers, Python tools, OpenAPI spec, backend filter endpoint, webhook
  validator HMAC, MCP connection)
- 6 scripts (deploy idempotente con fallback ADK, undeploy, reset,
  check-adk-version, new-specialist scaffold, eval-agents runner)
- 4 eval pieces (linter de best practices, runner, smoke-test, direct
  backend probe) + scenario templates
- 8 subagentes Claude (.claude/agents/) — wxo-architect, wxo-agent-author,
  wxo-tool-author, runbook-author, mock-builder, backend-tool-builder,
  eval-author, web-layer-builder
- Skill bundle fit-wxo-bootstrap/ (SKILL.md + 3 templates) listo para
  copiar a ~/.claude/skills/
- Web layer default FastAPI+HTMX con vista timeline observable + endpoint
  receptor de trazas
- Docker compose Coolify-ready (healthcheck wget -qO-, sin labels Traefik,
  network split internal:true)
- CI Gitea workflow con lint + smoke

Best practices enforced por evals/lint_wxo_yaml.py:
- A1: máx 10 tools por agente
- A3: orchestrator sin tools de remediación
- A6: agente sin propósito (react sin tools ni KB)
- T1: @observable_tool obligatorio, no @tool directo
- T3: _compat shim inline en tools.py
- D1: docker-compose sin wget --spider
- I-005: OpenAPI con description per-operation
- I-009: sin labels Traefik manuales

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

wxo/tools/python/_coercion_helpers.py

@@ -0,0 +1,90 @@
+"""Pydantic coercion helpers for tool input schemas.
+
+LLMs stringify everything — they send `"95727067"` when your schema
+expects `int`, or `'[{"id":1}]'` when you expect `list[dict]`. Pydantic
+strict mode returns 422 and the agent fails.
+
+Use these as `mode="before"` validators on every tool input schema.
+
+Example:
+
+    from pydantic import BaseModel, field_validator
+    from wxo.tools.python._coercion_helpers import _coerce_int, _coerce_list
+
+    class ResetPasswordInput(BaseModel):
+        user_id: int
+        groups: list[str]
+        _coerce_user_id = field_validator("user_id", mode="before")(_coerce_int)
+        _coerce_groups = field_validator("groups", mode="before")(_coerce_list)
+
+See `docs/known-issues.md#i-003` for the full story.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def _coerce_int(v: Any) -> Any:
+    """Accepts int or stringified int."""
+    if isinstance(v, str):
+        s = v.strip()
+        if s.lstrip("-").isdigit():
+            return int(s)
+    return v
+
+
+def _coerce_float(v: Any) -> Any:
+    if isinstance(v, str):
+        try:
+            return float(v.strip())
+        except ValueError:
+            pass
+    return v
+
+
+def _coerce_bool(v: Any) -> Any:
+    """Accepts bool, 'true'/'false', '1'/'0', 'yes'/'no'."""
+    if isinstance(v, bool):
+        return v
+    if isinstance(v, str):
+        s = v.strip().lower()
+        if s in ("true", "1", "yes", "y"):
+            return True
+        if s in ("false", "0", "no", "n"):
+            return False
+    return v
+
+
+def _coerce_list(v: Any) -> Any:
+    """Accepts list, stringified JSON list, or single value (wrapped)."""
+    if isinstance(v, list):
+        return v
+    if isinstance(v, str):
+        s = v.strip()
+        if s.startswith("[") and s.endswith("]"):
+            try:
+                parsed = json.loads(s)
+                if isinstance(parsed, list):
+                    return parsed
+            except json.JSONDecodeError:
+                pass
+        # Fallback: wrap single value
+        return [v]
+    return v
+
+
+def _coerce_dict(v: Any) -> Any:
+    """Accepts dict or stringified JSON dict."""
+    if isinstance(v, dict):
+        return v
+    if isinstance(v, str):
+        s = v.strip()
+        if s.startswith("{") and s.endswith("}"):
+            try:
+                parsed = json.loads(s)
+                if isinstance(parsed, dict):
+                    return parsed
+            except json.JSONDecodeError:
+                pass
+    return v

wxo/tools/python/_observable_tool.py

@@ -0,0 +1,178 @@
+"""Observable tool decorator.
+
+Wraps the ADK `@tool` so every call emits a structured trace
+(inputs, outputs, latency, side effects). See `docs/observability-pattern.md`.
+
+Usage:
+    from wxo.tools.python._observable_tool import observable_tool
+
+    @observable_tool(name="reset_password", domain="ad")
+    def reset_password(username: str) -> dict:
+        # your logic
+        return {"temp_password": "xxx"}
+
+The decorated function is still a valid ADK `@tool` — the decorator delegates.
+The LLM sees only `result`. The full trace goes to the configured sink.
+
+Sinks (controlled by env var TRACE_SINK):
+- `sqlite` (default): writes to `traces.db` next to the process
+- `http`: POST to $TRACE_SINK_URL (default http://web:8000/api/traces)
+- `otlp`: OpenTelemetry OTLP gRPC to $OTEL_EXPORTER_OTLP_ENDPOINT
+
+Set `_bypass_tracing=True` in the decorator to skip tracing for a specific
+tool (rare — used for hot-path tools or debug).
+"""
+from __future__ import annotations
+
+import functools
+import json
+import os
+import sqlite3
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+# === inline compat shim (NO eliminar — TRM lo necesita) ===
+try:
+    from ibm_watsonx_orchestrate.agent_builder.tools import tool as _adk_tool
+except ImportError:
+    def _adk_tool(*args, **kwargs):
+        def deco(f): return f
+        return deco if not args else deco(args[0])
+# ============================================================
+
+
+TRACE_SINK = os.environ.get("TRACE_SINK", "sqlite")
+TRACE_SINK_URL = os.environ.get("TRACE_SINK_URL", "http://web:8000/api/traces")
+TRACES_DB_PATH = os.environ.get("TRACES_DB_PATH", "/tmp/traces.db")
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _emit_trace(trace: dict[str, Any]) -> None:
+    """Send the trace to the configured sink. Failures must NEVER break the tool."""
+    try:
+        if TRACE_SINK == "sqlite":
+            _emit_sqlite(trace)
+        elif TRACE_SINK == "http":
+            _emit_http(trace)
+        elif TRACE_SINK == "otlp":
+            _emit_otlp(trace)
+        # else: silently drop (TRACE_SINK=off)
+    except Exception:
+        # Never let observability break the tool.
+        pass
+
+
+def _emit_sqlite(trace: dict[str, Any]) -> None:
+    conn = sqlite3.connect(TRACES_DB_PATH)
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS traces (
+            trace_id TEXT PRIMARY KEY,
+            tool TEXT,
+            domain TEXT,
+            agent_caller TEXT,
+            correlation_id TEXT,
+            started_at TEXT,
+            duration_ms INTEGER,
+            payload TEXT
+        )
+    """)
+    conn.execute("CREATE INDEX IF NOT EXISTS ix_traces_started ON traces (started_at)")
+    conn.execute(
+        "INSERT OR REPLACE INTO traces VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+        (
+            trace["trace_id"], trace["tool"], trace.get("domain"),
+            trace.get("agent_caller"), trace.get("correlation_id"),
+            trace["started_at"], trace["duration_ms"],
+            json.dumps(trace),
+        ),
+    )
+    conn.commit()
+    conn.close()
+
+
+def _emit_http(trace: dict[str, Any]) -> None:
+    import requests
+    requests.post(TRACE_SINK_URL, json=trace, timeout=2)
+
+
+def _emit_otlp(trace: dict[str, Any]) -> None:
+    # Stub. Requires opentelemetry-sdk + exporter. Implement in v2.
+    pass
+
+
+def observable_tool(
+    *,
+    name: str,
+    domain: str = "",
+    description: str | None = None,
+    _bypass_tracing: bool = False,
+):
+    """Decorator that wraps ADK `@tool` with structured tracing."""
+    def decorator(func: Callable) -> Callable:
+        # First wrap the function to capture traces.
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if _bypass_tracing:
+                return func(*args, **kwargs)
+
+            trace_id = f"{domain or 'tool'}-{name}-{uuid.uuid4().hex[:6]}"
+            started = time.perf_counter()
+            started_iso = _now_iso()
+
+            inputs = {}
+            try:
+                inputs = kwargs.copy()
+                # positional → harder; we capture the dict for now
+                if args:
+                    inputs["_positional"] = [repr(a)[:200] for a in args]
+            except Exception:
+                pass
+
+            result = None
+            error = None
+            try:
+                result = func(*args, **kwargs)
+            except Exception as e:
+                error = repr(e)
+                raise
+            finally:
+                duration_ms = int((time.perf_counter() - started) * 1000)
+                trace = {
+                    "trace_id": trace_id,
+                    "tool": name,
+                    "domain": domain,
+                    "started_at": started_iso,
+                    "duration_ms": duration_ms,
+                    "inputs": inputs,
+                    "result_preview": _preview(result),
+                    "error": error,
+                    "agent_caller": os.environ.get("WXO_CURRENT_AGENT", "unknown"),
+                    "correlation_id": os.environ.get("WXO_CORRELATION_ID", ""),
+                }
+                _emit_trace(trace)
+            return result
+
+        # Then wrap with the ADK tool decorator so it's discoverable.
+        kwargs = {"name": name}
+        if description:
+            kwargs["description"] = description
+        return _adk_tool(**kwargs)(wrapper)
+    return decorator
+
+
+def _preview(value: Any, max_len: int = 500) -> Any:
+    """Truncate big values for trace storage."""
+    if value is None:
+        return None
+    try:
+        s = json.dumps(value, default=str)
+        if len(s) <= max_len:
+            return json.loads(s)
+        return {"_truncated": True, "preview": s[:max_len]}
+    except Exception:
+        return {"_repr": repr(value)[:max_len]}

wxo/tools/python/_template_tools.py

@@ -0,0 +1,136 @@
+"""Template — Python tools wrapper.
+
+Reemplazar REPLACE_* con los valores de tu caso. Una función por endpoint
+mockeado o por acción atómica. Máx 10 funciones por archivo (regla A1 —
+si necesitás más, partí en specialists).
+
+Patrón:
+- Cada función usa `@observable_tool` (NO `@tool` directo — regla T1).
+- Cada función con input no-trivial declara un schema Pydantic con
+  coerción explícita (regla T2 — issue I-003).
+- BASE_URL viene del env de la connection, nunca hardcoded (regla T4).
+- Compat shim inline al inicio del archivo (regla T3 — issue I-010).
+"""
+from __future__ import annotations
+
+# === inline compat shim (NO eliminar — TRM lo necesita) ===
+try:
+    from ibm_watsonx_orchestrate.agent_builder.tools import tool as _adk_tool
+except ImportError:
+    def _adk_tool(*args, **kwargs):
+        def deco(f): return f
+        return deco if not args else deco(args[0])
+# ============================================================
+
+import os
+import requests
+from pydantic import BaseModel, field_validator
+from typing import Optional
+
+# Imports de helpers del template — ABSOLUTOS, no relativos (regla T3).
+# Cuando este archivo se importe en el TRM, los _observability/_coercion
+# tienen que estar en sys.path. El deploy script los inlinea o los
+# distribuye junto.
+try:
+    from wxo.tools.python._observable_tool import observable_tool
+    from wxo.tools.python._coercion_helpers import _coerce_int, _coerce_list, _coerce_bool
+except ImportError:
+    # Fallback si los helpers no están disponibles en el TRM:
+    # observable_tool degrada a @tool puro, coerción degrada a identidad.
+    def observable_tool(*, name, domain="", description=None, _bypass_tracing=False):
+        def deco(f):
+            return _adk_tool(name=name, description=description)(f) if description else _adk_tool(name=name)(f)
+        return deco
+    def _coerce_int(v): return int(v) if isinstance(v, str) and v.strip().isdigit() else v
+    def _coerce_list(v): return [v] if isinstance(v, str) else v
+    def _coerce_bool(v): return v
+
+
+# BASE_URL viene de la connection. NUNCA hardcoded.
+BASE_URL = os.environ.get("BASE_URL", "")
+TIMEOUT_SEC = int(os.environ.get("TOOL_TIMEOUT_SEC", "10"))
+
+
+# ─── Input schemas with coercion ────────────────────────────────────────────
+
+class LookupInput(BaseModel):
+    username: str
+
+class ExecuteInput(BaseModel):
+    target_id: int
+    options: list[str] = []
+    notify: bool = True
+    # Coerciones explícitas — el LLM stringifica todo (issue I-003)
+    _coerce_id = field_validator("target_id", mode="before")(_coerce_int)
+    _coerce_opts = field_validator("options", mode="before")(_coerce_list)
+    _coerce_notify = field_validator("notify", mode="before")(_coerce_bool)
+
+
+# ─── Tools ──────────────────────────────────────────────────────────────────
+
+@observable_tool(
+    name="REPLACE_lookup",
+    domain="REPLACE_domain",
+    description="REPLACE — busca un recurso por identificador y devuelve sus datos."
+)
+def REPLACE_lookup(username: str) -> dict:
+    """REPLACE descripción de qué hace esta tool.
+
+    Args:
+        username: REPLACE qué es el username
+
+    Returns:
+        dict con campos: REPLACE qué campos devuelve
+    """
+    resp = requests.post(
+        f"{BASE_URL}/users/lookup",
+        json={"username": username},
+        timeout=TIMEOUT_SEC,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+@observable_tool(
+    name="REPLACE_execute",
+    domain="REPLACE_domain",
+    description="REPLACE — ejecuta la acción principal contra el sistema externo."
+)
+def REPLACE_execute(target_id: int, options: Optional[list[str]] = None, notify: bool = True) -> dict:
+    """REPLACE descripción.
+
+    Args:
+        target_id: REPLACE
+        options: REPLACE
+        notify: REPLACE
+
+    Returns:
+        dict con: REPLACE
+    """
+    payload = {
+        "target_id": target_id,
+        "options": options or [],
+        "notify": notify,
+    }
+    resp = requests.post(
+        f"{BASE_URL}/execute",
+        json=payload,
+        timeout=TIMEOUT_SEC,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+@observable_tool(
+    name="REPLACE_get_status",
+    domain="REPLACE_domain",
+    description="REPLACE — devuelve el estado actual de un recurso."
+)
+def REPLACE_get_status(resource_id: str) -> dict:
+    """REPLACE descripción."""
+    resp = requests.get(
+        f"{BASE_URL}/status/{resource_id}",
+        timeout=TIMEOUT_SEC,
+    )
+    resp.raise_for_status()
+    return resp.json()

wxo/tools/python/requirements.txt

@@ -0,0 +1,2 @@
+requests>=2.31.0
+pydantic>=2.5.0