Sales Agent Expert (post redesign 2026-04)

Antes de codear: skill + plan + tech-debt-log. Plan: docs/domains/sales-agent/redesign-2026-04/README.md (S00–S12 cerrado).

§0 — Anti-duplication cardinal (read first)

Origen: PR-1 PI-1.1 hotfix 2026-05-01. Builder agentic creó modules/sales_agent/observability/recording/turn_envelope.py mirror de modules/copilot/observability/recording/turn_envelope.py existente. REVERT obligatorio.

Observability + cost + pricing + channel-format + callback-handler + FX + tenant-billing + PII patterns son shared abstractions. Vivien (o deben vivir) en shared/agent_observability/.

ANTES de crear archivo nuevo en modules/sales_agent/observability/recording/<X>.py o modules/sales_agent/observability/<subsystem>/<X>.py:

1. Consultá inventario canónico: cat .claude/rules/anti-duplication.md — buscá tu subsystem en tabla
2. Grep cross-codebase: find /home/chris/AISALESHT/backend/src -name "<basename>.py" + grep -rn "class <ClassName>" backend/src/shared/ backend/src/modules/
3. Si match en modules/copilot/<same-path> o shared/<subsystem> → STOP, escalate /pm. Tres opciones:
   • EXTEND: heredar desde shared base
   • LIFT-TO-SHARED: subir abstracción a shared, después sales_agent + copilot consumen
   • NEW (último recurso): justificar path:line por qué existing no sirve

NUNCA mirror turn_envelope.py / callback_handler.py / cost_calculator.py / fx_resolver.py / similar de copilot a sales_agent. Si copilot lo tiene Y sales_agent lo necesita → la SEGUNDA invocación dispara LIFT-TO-SHARED, no MIRROR.

§3 — NO se toca

Tocar §3 → PARAR, preguntar al usuario.

Antes de codear (orden estricto)

1. Trazas primero. Bug → query sales_agent_trace_event + sales_agent_llm_call. Sin traza del síntoma → bug del recorder, fix antes que el síntoma.
2. Plan + tech-debt-log + learnings. Decisiones cross-fase viven en learnings/S{0..12}-*.md.
3. grep AST de surface, no asumir. Paths cambian; SSoT no.
4. Ambiguo → preguntar antes de tocar.

Anti-patterns (cerrados)

• ❌ Migrar StateGraph a deepagents.
• ❌ Eliminar Closer Studio + WS + buffer + OutputManager + follow_up_engine + frozen_detection.
• ❌ Subagents deepagents.
• ❌ Hardcodear model wire-name strings en specialists. Usar LLM_ROLE_BY_SITE SSoT.
• ❌ Hardcodear canales literales en OutputManager. Usar get_channel_format(channel_type).
• ❌ Importar copilot/ desde sales_agent/ (o viceversa). Ambos consumen shared/.
• ❌ Tocar PromptVersionModel.
• ❌ from __future__ import annotations en */orchestrator/graph.py (rompe LangGraph runtime introspection).
• ❌ Bypass sanitize_payload en writes a *_trace_event o *_llm_call.
• ❌ Duplicar plumbing del BaseAgentCallbackHandler shared. Solo overrides agent-specific.
• ❌ Bypass channel registry shared. Nuevo canal → register_channel en startup.
• ❌ Crear feature branches/worktrees salvo instrucción explícita. Todo en development.
• ❌ Aliases DeepSeek retired Jul 24 2026 (deepseek-chat, deepseek-reasoner). Usar deepseek-v4-flash / deepseek-v4-pro. Arch ratchet bloquea.
• ❌ Tier pricing >200k tokens sin resolver. Si LiteLLM declara input_cost_per_token_above_200k_tokens, calculator debe split (TIER_THRESHOLD = 200_000). Arch ratchet.

Decisiones cross-fase no obvias

• BaseAgentCallbackHandler Template Method (S0/S11A) — subclase implementa solo _persist_llm_call_row + _persist_trace_event_row. DRY threshold = 2 consumers (sales + copilot).
• compose_system_prompt(fragments) + CACHE_BOUNDARY_MARKER (S3) — slots cacheable cross-tenant → cacheable per-tenant → volatile. Hit rate ≥60% si prefix ≥1024 tokens.
• model_pricing_snapshot cross-agent en shared/ — reference data global. Tier pricing >200k via raw_payload JSONB.
• Dual-write 4 sem pre-cutover legacy — reconciliation worker mide drift; cutover prematuro rompe sales_audit.py dual-read.
• LLM_ROLE_BY_SITE superset + SPECIALIST_TO_ROLE sub-view — specialists back-compat; summary + nudge + safety centralizados.
• Tenant isolation en CADA query (incluido get_by_id).
• FastAPI(redirect_slashes=False) — Next.js proxy strips body en 307. App-level only.
• PII regex sync (no Presidio) — WONT-FIX (S12) — Presidio overhead 50-200ms incompatible con hot path <10ms p99. Reabrir solo con enterprise contract.
• typing_simulation_cpm (S12) — registry override per-canal, fallback CPM_SPEED cuando None / 0 / negativo.
• Voz del agente — voseo del tenant respetado — .claude/rules/spanish-text.md NO aplica al output del agente. Voseo del tenant es feature.

SSoT vivos

Checklist pre-commit "senior dev pass"

1. ¿Toca §3? → escalé al usuario.
2. ¿Test reproductor antes del fix? RED → GREEN.
3. ¿Pasa por SSoT (channels / models / pricing / LLM_ROLE / personality)?
4. ¿sanitize_payload en cada write a observability tables?
5. ¿tenant_id filter en CADA query?
6. ¿response_model= en endpoint nuevo? PII removido / mascarado / justificado.
7. ¿Spanish neutro LATAM en user-facing? Voz del tenant respetada en output del agente.
8. ¿Stage por nombre en commit (no -A ni .)?
9. ¿Arch tests verde native?
10. ¿Tech-debt-log actualizado? Cada entry → fase concreta o WONT-FIX con razón.

Glossary

• turn: 1 webhook/POST. 1 turn_start + 1 turn_end + N llm_call/tool_call.
• callback handler: BaseAgentCallbackHandler + subclase. Best-effort (try/except + structlog warning + rollback).
• LLM_ROLE_BY_SITE: SSoT site → ModelRole. Arch ratchet sin allowlist.
• channel registry: register_channel + get_channel_format cross-agent. 7 baseline.
• specialist: Nodo StateGraph (qualifier / product_expert / closer / supervisor / tool_executor / safety / escalate).
• dual-write: Escribir legacy + nueva durante 4 sem. Cutover post-window.
• ratchet: Test que solo permite shrink.
• Stranger Fig: Refactor incremental, snapshot diff = 0 byte-equal per commit.
• §3: Surfaces protegidas. Tocar = preguntar.
• Tier pricing: LiteLLM input_cost_per_token_above_200k_tokens. Calculator split en 200_000 (S12).

Pointers

• CLAUDE.md raíz.
• docs/domains/sales-agent/redesign-2026-04/{README,00-vision-and-objectives,02-architecture-target,04-principles,05-tech-debt-log}.md.
• .claude/rules/{copilot-resilience,copilot-observability,sales-agent-brand-voice,parallel-safety,spanish-text}.md.
• references/ (pre-redesign conversation craft — útil para evolución de copy, no arquitectura post-S12).

Budget + Outbound Gating (PI-1 S0 PR-2)

sales_agent está subject a 2 gates del módulo shared/billing/ + shared/compliance/ (PI-1 S0 PR-2 — wiring specialists diferido a S2; primitivas expuestas hoy).

Gate 1 — BudgetGuard.check (LLM cost, SA pool reservado)

decision = await budget_guard.check(
    tenant_id=tenant_id,
    agent_kind="sales_agent",       # ← bucket SA (reserved pool)
    estimated_cost_usd=Decimal("..."),  # tier-aware si LiteLLM declara input_cost_per_token_above_200k_tokens (Kimi K2.6, S12)
)

• agent_kind="sales_agent" → consume del SA pool reservado (plan_config.llm_budget_total_usd * sales_agent_reserved_pct, default 50%).
• SA exhausto NO consume Others pool (copilot reserve). Hard separation por bucket. Arch test property-based enforce.
• Tier pricing >200k (Kimi K2.6, S12 cementado): caller (specialist) pre-computes estimated_cost_usd con TIER_THRESHOLD = 200_000 split. BudgetGuard NO recomputa tiers (no invade calculator §3-protected).

Gate 2 — OutboundRateLimiter.check (volumen mensajes outbound)

allowed = await outbound_rate_limiter.check(tenant_id=tenant_id)
if not allowed:
    # short-circuit pre-send: log + skip OutputManager.process_response chunking
    ...

• Sliding window Redis (24h) con cap plan_config.max_outbound_msg_per_day.
• None cap → unlimited (subject a budget).
• Soft-fail: Redis unavailable → fail-open (per tessl__graceful-degradation).

Plan defaults (editable Streamlit /planes-billing — 1 UPDATE row, 0 migration)

Custom override per-tenant

tenant_subscription.custom_overrides JSONB permite per-tenant override (ej. tenant enterprise con {"max_outbound_msg_per_day": 50000, "llm_budget_total_usd": 200}). PlanService.get_effective(tenant_id) mergea overrides sobre plan base. Cache 5min con cross-instance pub/sub invalidation (PR-2 Q5).

MV stale soft cap

Si mv_refresh_log.get_last_refresh('mv_daily_llm_cost_per_tenant_v2') > 1h → BudgetGuard aplica soft cap 105% (admite 5% overrun para no bloquear ventas). Cementado PR-2 Q4.

Cuándo wirear (S2)

PR-2 expone primitivas, NO modifica specialists. S2 wirea:

• qualifier / product_expert / closer / supervisor antes de cada LLM call → BudgetGuard.check.
• OutputManager.send_outbound_message → OutboundRateLimiter.check antes de process_response.

§3 protected surfaces (Closer Studio, BufferService, OutputManager.process_response chunking) NO se tocan — el gate vive antes del entry point.

Detalle vivo en PR-2 CONTRACT.md. Skill solo agrega anchor — ver: docs/pm-nico/pis/active/PI-1-campaigns-module/sprints/S0-foundation/prs/PR-2-billing-and-compliance/CONTRACT.md

Project invariants (read on demand)

• references/sales-agent-brand-voice.md — SSoT voz, compiler v2, slot architecture, micro-anchor per-turn, cache invalidation, tests obligatorios