santismm-knowledge-mcp 0.2.1

package/content/patterns/routing.json

@@ -0,0 +1,294 @@
+{
+  "slug": "routing",
+  "category": "orchestration",
+  "updated": "2026-06-24",
+  "version": "1.1",
+  "technologies": [
+    "Classifier models",
+    "LangGraph",
+    "Model routers",
+    "Rules engines"
+  ],
+  "related": [
+    "prompt-chaining",
+    "orchestrator-workers",
+    "parallelization"
+  ],
+  "references": [
+    {
+      "title": "Anthropic — Building Effective Agents (2024)",
+      "url": "https://www.anthropic.com/research/building-effective-agents"
+    }
+  ],
+  "evidence": {
+    "evidenceLevel": "production",
+    "confidenceLevel": "low",
+    "sourceType": ["production_system", "personal_experience", "industry_observation"]
+  },
+  "locales": {
+    "en": {
+      "name": "Routing",
+      "summary": "Routing classifies an input and directs it to the most appropriate specialized handler, prompt or model. It improves quality by letting each path be optimized for its case, and controls cost by sending easy requests to cheap models and hard ones to capable models.",
+      "definition": "Routing is a pattern that classifies each incoming request and dispatches it to the most appropriate handler or model, so easy inputs use cheap paths and hard inputs use capable ones.",
+      "problem": "A single prompt or model handling every kind of input does each one worse, and using one expensive model for everything wastes money on easy requests.",
+      "context": "Use routing when inputs fall into distinct categories that benefit from different handling — different prompts, tools, models or workflows — and the categories can be classified reliably.",
+      "solution": [
+        "A lightweight classifier (an LLM call or a model) labels the input, then a router sends it to the matching downstream handler. Each handler is specialized and optimized for its category.",
+        "Routing also enables cost-performance tiering: route simple queries to a fast, cheap model and complex ones to a stronger reasoning model, paying for capability only when it is needed."
+      ],
+      "components": [
+        "Classifier",
+        "Routing logic",
+        "Specialized handlers",
+        "Fallback / default route"
+      ],
+      "benefits": [
+        "Each path is optimized for its case, raising quality.",
+        "Cost control by tiering models to difficulty.",
+        "Separation of concerns keeps each handler simple."
+      ],
+      "risks": [
+        "Misclassification sends inputs down the wrong path.",
+        "The classifier adds a step and some latency.",
+        "Category drift over time degrades routing accuracy."
+      ],
+      "whenNot": [
+        "When inputs are homogeneous — one handler suffices.",
+        "When categories cannot be classified reliably.",
+        "When the added classification step is not worth the gain."
+      ],
+      "examples": [
+        "Routing support tickets to billing, technical or sales handlers.",
+        "Sending simple questions to a small model and hard ones to a reasoning model.",
+        "Directing different document types to type-specific extractors."
+      ],
+      "productionEvidence": {
+        "context": "Single-operator, local-first OpenClaw deployment observed over 57 days (161 sessions / 2,776 turns), aggregated from the agent's own trajectory traces.",
+        "scenario": "Inbound channel messages and autonomous wake-ups are routed to one agent through distinct entrypoints, with channel/peer/role bindings selecting the session.",
+        "technology": "Binding + route registry (resolveAgentRoute), per-channel session keys, and a resolved-route cache.",
+        "load": "3 channels (Telegram, web chat, WhatsApp) and 4 trigger kinds (user, heartbeat, cron, memory).",
+        "results": "Routing held across all three channels and four trigger types with no misroute surfacing as a failure (98.8% session success overall). Single-operator local-first deployment — a working reference, not a scale benchmark."
+      },
+      "kpis": [
+        {
+          "metric": "Routing accuracy",
+          "note": "Share of inputs sent to the correct handler/model; the single metric that defines the pattern's value."
+        },
+        {
+          "metric": "Cost savings vs. always-best-model",
+          "note": "Money saved by routing easy inputs to cheaper models instead of the top one for everything."
+        },
+        {
+          "metric": "Misroute cost",
+          "note": "The downstream damage of wrong routes — a misroute can cost far more than the savings it chased."
+        },
+        {
+          "metric": "Router latency overhead",
+          "note": "Time the routing decision itself adds before any real work begins."
+        }
+      ],
+      "failureModes": [
+        "Misclassification: the router sends an input to the wrong model or path, degrading the answer.",
+        "Ambiguous inputs that don't fit any route cleanly and get forced into a poor one.",
+        "Router becomes a bottleneck or single point of failure for every request.",
+        "Drift: input distribution shifts over time and the router's categories go stale."
+      ],
+      "lessons": [
+        "Optimize for the cost of a misroute, not just routing accuracy — some wrong routes are far costlier than others.",
+        "Add a default / fallback route for inputs that match nothing well.",
+        "Keep the router cheap and fast; if it costs as much as the work, it defeats the purpose.",
+        "Monitor input drift and re-tune routes as the distribution changes."
+      ],
+      "faqs": [
+        {
+          "q": "What classifies the input?",
+          "a": "Usually a lightweight LLM call or a dedicated classifier model; for clear-cut cases, deterministic rules can route without a model."
+        },
+        {
+          "q": "How does routing save cost?",
+          "a": "By tiering: easy requests go to cheap, fast models and only hard ones reach expensive reasoning models, so you pay for capability only when needed."
+        },
+        {
+          "q": "What if the classifier is wrong?",
+          "a": "Provide a sensible default route and monitor misroutes; a fallback handler and good observability limit the impact of misclassification."
+        }
+      ]
+    },
+    "es": {
+      "name": "Enrutamiento (Routing)",
+      "summary": "El enrutamiento clasifica una entrada y la dirige al manejador, prompt o modelo especializado más adecuado. Mejora la calidad al optimizar cada camino para su caso y controla el coste enviando peticiones fáciles a modelos baratos y las difíciles a modelos capaces.",
+      "definition": "El enrutado es un patrón que clasifica cada petición entrante y la despacha al manejador o modelo más apropiado, de modo que las entradas fáciles usan caminos baratos y las difíciles, modelos capaces.",
+      "problem": "Un solo prompt o modelo manejando cada tipo de entrada hace cada una peor, y usar un modelo caro para todo malgasta dinero en peticiones fáciles.",
+      "context": "Usa el enrutamiento cuando las entradas caen en categorías distintas que se benefician de un manejo diferente —distintos prompts, herramientas, modelos o flujos— y las categorías se pueden clasificar de forma fiable.",
+      "solution": [
+        "Un clasificador ligero (una llamada al LLM o un modelo) etiqueta la entrada, y luego un enrutador la envía al manejador adecuado. Cada manejador está especializado y optimizado para su categoría.",
+        "El enrutamiento también permite escalonar coste-rendimiento: enruta consultas simples a un modelo rápido y barato y las complejas a un modelo de razonamiento más fuerte, pagando por capacidad solo cuando hace falta."
+      ],
+      "components": [
+        "Clasificador",
+        "Lógica de enrutamiento",
+        "Manejadores especializados",
+        "Ruta por defecto / fallback"
+      ],
+      "benefits": [
+        "Cada camino se optimiza para su caso, elevando la calidad.",
+        "Control de coste escalonando modelos según la dificultad.",
+        "La separación de responsabilidades mantiene simple cada manejador."
+      ],
+      "risks": [
+        "La mala clasificación envía entradas por el camino equivocado.",
+        "El clasificador añade un paso y algo de latencia.",
+        "La deriva de categorías en el tiempo degrada la precisión."
+      ],
+      "whenNot": [
+        "Cuando las entradas son homogéneas: basta un manejador.",
+        "Cuando las categorías no se pueden clasificar de forma fiable.",
+        "Cuando el paso de clasificación añadido no compensa la ganancia."
+      ],
+      "examples": [
+        "Enrutar tickets de soporte a manejadores de facturación, técnico o ventas.",
+        "Enviar preguntas simples a un modelo pequeño y las difíciles a uno de razonamiento.",
+        "Dirigir distintos tipos de documento a extractores específicos por tipo."
+      ],
+      "productionEvidence": {
+        "context": "Despliegue OpenClaw local-first y mono-operador observado durante 57 días (161 sesiones / 2.776 turnos), agregado desde las propias trazas del agente.",
+        "scenario": "Los mensajes entrantes de canal y los despertares autónomos se enrutan a un agente por entrypoints distintos, con bindings de canal/peer/rol que seleccionan la sesión.",
+        "technology": "Registro de bindings y rutas (resolveAgentRoute), claves de sesión por canal y caché de ruta resuelta.",
+        "load": "3 canales (Telegram, chat web, WhatsApp) y 4 tipos de trigger (usuario, heartbeat, cron, memoria).",
+        "results": "El enrutado se mantuvo en los tres canales y los cuatro tipos de trigger sin que ningún error de ruta apareciera como fallo (98,8% de éxito por sesión). Despliegue local-first mono-operador — una referencia que funciona, no un benchmark de escala."
+      },
+      "kpis": [
+        {
+          "metric": "Precisión de enrutado",
+          "note": "Proporción de entradas enviadas al manejador/modelo correcto; la métrica que define el valor del patrón."
+        },
+        {
+          "metric": "Ahorro vs. usar siempre el mejor modelo",
+          "note": "Dinero ahorrado al enrutar entradas fáciles a modelos más baratos en vez del mejor para todo."
+        },
+        {
+          "metric": "Coste de mal enrutado",
+          "note": "El daño posterior de rutas erróneas; un mal enrutado puede costar mucho más que el ahorro buscado."
+        },
+        {
+          "metric": "Sobrecoste de latencia del router",
+          "note": "Tiempo que la propia decisión de enrutado añade antes de empezar el trabajo real."
+        }
+      ],
+      "failureModes": [
+        "Mala clasificación: el router envía una entrada al modelo o ruta equivocados, degradando la respuesta.",
+        "Entradas ambiguas que no encajan bien en ninguna ruta y se fuerzan a una deficiente.",
+        "El router se convierte en cuello de botella o punto único de fallo de cada petición.",
+        "Deriva: la distribución de entradas cambia con el tiempo y las categorías del router quedan obsoletas."
+      ],
+      "lessons": [
+        "Optimiza por el coste de un mal enrutado, no solo por la precisión: algunas rutas erróneas son mucho más caras que otras.",
+        "Añade una ruta por defecto / de respaldo para entradas que no encajen bien en nada.",
+        "Mantén el router barato y rápido; si cuesta tanto como el trabajo, pierde su sentido.",
+        "Monitoriza la deriva de entradas y reajusta las rutas cuando cambie la distribución."
+      ],
+      "faqs": [
+        {
+          "q": "¿Qué clasifica la entrada?",
+          "a": "Normalmente una llamada ligera al LLM o un modelo clasificador dedicado; para casos claros, reglas deterministas pueden enrutar sin modelo."
+        },
+        {
+          "q": "¿Cómo ahorra coste el enrutamiento?",
+          "a": "Escalonando: las peticiones fáciles van a modelos baratos y rápidos y solo las difíciles llegan a modelos de razonamiento caros, así pagas por capacidad solo cuando hace falta."
+        },
+        {
+          "q": "¿Y si el clasificador se equivoca?",
+          "a": "Provee una ruta por defecto sensata y monitoriza los errores de ruta; un manejador de respaldo y buena observabilidad limitan el impacto de la mala clasificación."
+        }
+      ]
+    },
+    "pt": {
+      "name": "Roteamento (Routing)",
+      "summary": "O roteamento classifica uma entrada e a direciona ao manipulador, prompt ou modelo especializado mais adequado. Melhora a qualidade ao otimizar cada caminho para seu caso e controla o custo enviando requisições fáceis a modelos baratos e as difíceis a modelos capazes.",
+      "definition": "O roteamento é um padrão que classifica cada requisição recebida e a despacha ao manipulador ou modelo mais apropriado, de modo que entradas fáceis usam caminhos baratos e as difíceis, modelos capazes.",
+      "problem": "Um único prompt ou modelo lidando com cada tipo de entrada faz cada uma pior, e usar um modelo caro para tudo desperdiça dinheiro em requisições fáceis.",
+      "context": "Use o roteamento quando as entradas caem em categorias distintas que se beneficiam de tratamento diferente — diferentes prompts, ferramentas, modelos ou fluxos — e as categorias podem ser classificadas de forma confiável.",
+      "solution": [
+        "Um classificador leve (uma chamada ao LLM ou um modelo) rotula a entrada, e então um roteador a envia ao manipulador adequado. Cada manipulador é especializado e otimizado para sua categoria.",
+        "O roteamento também permite escalonar custo-desempenho: roteie consultas simples a um modelo rápido e barato e as complexas a um modelo de raciocínio mais forte, pagando por capacidade só quando necessário."
+      ],
+      "components": [
+        "Classificador",
+        "Lógica de roteamento",
+        "Manipuladores especializados",
+        "Rota padrão / fallback"
+      ],
+      "benefits": [
+        "Cada caminho é otimizado para seu caso, elevando a qualidade.",
+        "Controle de custo escalonando modelos conforme a dificuldade.",
+        "A separação de responsabilidades mantém cada manipulador simples."
+      ],
+      "risks": [
+        "A má classificação envia entradas pelo caminho errado.",
+        "O classificador adiciona um passo e alguma latência.",
+        "A deriva de categorias ao longo do tempo degrada a precisão."
+      ],
+      "whenNot": [
+        "Quando as entradas são homogêneas: basta um manipulador.",
+        "Quando as categorias não podem ser classificadas de forma confiável.",
+        "Quando o passo de classificação adicionado não compensa o ganho."
+      ],
+      "examples": [
+        "Rotear chamados de suporte a manipuladores de faturamento, técnico ou vendas.",
+        "Enviar perguntas simples a um modelo pequeno e as difíceis a um de raciocínio.",
+        "Direcionar diferentes tipos de documento a extratores específicos por tipo."
+      ],
+      "productionEvidence": {
+        "context": "Implantação OpenClaw local-first e de operador único observada por 57 dias (161 sessões / 2.776 turnos), agregada a partir dos próprios rastros do agente.",
+        "scenario": "Mensagens de canal recebidas e despertares autônomos são roteados para um agente por entrypoints distintos, com bindings de canal/peer/papel selecionando a sessão.",
+        "technology": "Registro de bindings e rotas (resolveAgentRoute), chaves de sessão por canal e cache de rota resolvida.",
+        "load": "3 canais (Telegram, chat web, WhatsApp) e 4 tipos de gatilho (usuário, heartbeat, cron, memória).",
+        "results": "O roteamento se manteve nos três canais e nos quatro tipos de gatilho sem que nenhum erro de rota aparecesse como falha (98,8% de sucesso por sessão). Implantação local-first de operador único — uma referência que funciona, não um benchmark de escala."
+      },
+      "kpis": [
+        {
+          "metric": "Precisão de roteamento",
+          "note": "Proporção de entradas enviadas ao manipulador/modelo correto; a métrica que define o valor do padrão."
+        },
+        {
+          "metric": "Economia vs. usar sempre o melhor modelo",
+          "note": "Dinheiro economizado ao rotear entradas fáceis para modelos mais baratos em vez do melhor para tudo."
+        },
+        {
+          "metric": "Custo de roteamento errado",
+          "note": "O dano posterior de rotas erradas; um roteamento errado pode custar muito mais que a economia buscada."
+        },
+        {
+          "metric": "Sobrecusto de latência do roteador",
+          "note": "Tempo que a própria decisão de roteamento adiciona antes de começar o trabalho real."
+        }
+      ],
+      "failureModes": [
+        "Má classificação: o roteador envia uma entrada ao modelo ou rota errados, degradando a resposta.",
+        "Entradas ambíguas que não encaixam bem em nenhuma rota e são forçadas a uma deficiente.",
+        "O roteador vira gargalo ou ponto único de falha de cada requisição.",
+        "Deriva: a distribuição de entradas muda com o tempo e as categorias do roteador ficam obsoletas."
+      ],
+      "lessons": [
+        "Otimize pelo custo de um roteamento errado, não só pela precisão: algumas rotas erradas são muito mais caras que outras.",
+        "Adicione uma rota padrão / de fallback para entradas que não encaixem bem em nada.",
+        "Mantenha o roteador barato e rápido; se custa tanto quanto o trabalho, perde o sentido.",
+        "Monitore a deriva de entradas e reajuste as rotas quando a distribuição mudar."
+      ],
+      "faqs": [
+        {
+          "q": "O que classifica a entrada?",
+          "a": "Normalmente uma chamada leve ao LLM ou um modelo classificador dedicado; para casos claros, regras determinísticas podem rotear sem modelo."
+        },
+        {
+          "q": "Como o roteamento economiza custo?",
+          "a": "Escalonando: as requisições fáceis vão a modelos baratos e rápidos e só as difíceis chegam a modelos de raciocínio caros, então você paga por capacidade só quando necessário."
+        },
+        {
+          "q": "E se o classificador errar?",
+          "a": "Forneça uma rota padrão sensata e monitore os erros de rota; um manipulador de fallback e boa observabilidade limitam o impacto da má classificação."
+        }
+      ]
+    }
+  }
+}

package/content/patterns/sandboxed-execution.json

@@ -0,0 +1,311 @@
+{
+  "slug": "sandboxed-execution",
+  "category": "safety",
+  "updated": "2026-08-22",
+  "version": "1.0",
+  "technologies": [
+    "Containers",
+    "microVMs (Firecracker / gVisor)",
+    "Ephemeral workspaces",
+    "Resource quotas and timeouts",
+    "Scoped secret injection"
+  ],
+  "related": [
+    "least-privilege-tooling",
+    "egress-allowlist",
+    "recovery-strategy",
+    "human-approval-gate"
+  ],
+  "references": [
+    {
+      "title": "OWASP — Top 10 for LLM Applications",
+      "url": "https://genai.owasp.org/llm-top-10/"
+    },
+    {
+      "title": "MITRE ATLAS — Adversarial Threat Landscape for AI Systems",
+      "url": "https://atlas.mitre.org/"
+    },
+    {
+      "title": "NIST — AI Risk Management Framework (AI RMF 1.0)",
+      "url": "https://www.nist.gov/itl/ai-risk-management-framework"
+    }
+  ],
+  "evidence": {
+    "evidenceLevel": "industry_observation",
+    "confidenceLevel": "high",
+    "sourceType": [
+      "industry_observation",
+      "personal_experience",
+      "paper"
+    ]
+  },
+  "locales": {
+    "en": {
+      "name": "Sandboxed Execution",
+      "summary": "Run everything an agent generates or invokes inside a disposable, isolated environment with no ambient credentials, a bounded filesystem, controlled egress and hard resource caps. The sandbox is not there because the agent is malicious; it is there because the agent's input can be.",
+      "definition": "Sandboxed execution is the practice of running agent-generated code and agent-invoked actions inside an isolated, ephemeral environment whose filesystem, network, credentials and resources are bounded by the host rather than by the agent, so that a hijacked or mistaken agent cannot affect anything outside it.",
+      "problem": "An agent that executes code on the host inherits the host: its credentials, its filesystem, its network position. One successful injection or one confidently wrong command is then indistinguishable from a compromise of the machine.",
+      "context": "Use it whenever an agent runs code, executes shell commands, installs packages or processes untrusted files. The threshold is low: if the agent can cause execution, the execution belongs in a sandbox.",
+      "solution": [
+        "Make it ephemeral. Create the environment per task, destroy it after, and never carry state forward that the next task did not ask for. Persistence is how a one-off compromise becomes a foothold.",
+        "Remove ambient credentials. Nothing in the environment should be usable simply because it is present; inject only the narrowly scoped secrets the task needs, for its duration.",
+        "Bound the filesystem to the working set. Mount the repository or the input, nothing else, and mount read-only whatever does not need writing.",
+        "Constrain egress inside the sandbox, not around it. The isolation and the network policy are the same control from the attacker's point of view, and a sandbox with open network is a jail with a phone.",
+        "Cap resources — CPU, memory, disk, wall-clock, process count. Runaway consumption is the failure mode that arrives first and most often, usually without any adversary at all.",
+        "Log what crossed the boundary: which files came in, which came out, which destinations were reached. The boundary is only useful if you can see what passed through it."
+      ],
+      "components": [
+        "An isolation primitive: container, microVM or equivalent, chosen for the strength the workload needs.",
+        "Ephemeral lifecycle management, with destruction as the default rather than a cleanup step.",
+        "A secret-injection path scoped to the task and its duration.",
+        "A network policy applied inside the sandbox boundary.",
+        "Resource quotas and timeouts, enforced by the host.",
+        "Boundary logging: inputs, outputs and destinations."
+      ],
+      "benefits": [
+        "Converts 'the agent ran something bad' from an incident into a discarded container.",
+        "Makes it safe to give an agent genuine execution ability, which is often what makes it useful at all.",
+        "Bounds honest mistakes as well as attacks — the same control catches an infinite loop and an injected payload.",
+        "Gives a clean place to observe: everything the task touched crossed one boundary."
+      ],
+      "risks": [
+        "Isolation weaker than assumed: a shared kernel is not a security boundary against determined escape, and treating a container as a microVM is a category error.",
+        "Credentials smuggled in for convenience — one mounted config file undoes the whole pattern.",
+        "Sandboxes that quietly become persistent because rebuilding is slow, so the ephemerality that carried the guarantee is gone.",
+        "Escape via the shared surface that remains: mounted volumes, the orchestrator API, or the network the sandbox still reaches."
+      ],
+      "whenNot": [
+        "Read-only agents with no execution capability, where there is nothing to isolate and the cost buys nothing.",
+        "Latency-critical inline paths where environment startup dominates the task and a narrower control — a restricted interpreter, a pure function — fits better.",
+        "When the sandbox would need the very credentials it exists to withhold, which is a sign the task should be split rather than isolated."
+      ],
+      "examples": [
+        "A coding agent that clones into a fresh container per task, with the repository mounted, no cloud credentials present and egress limited to the package registry. A malicious dependency install destroys a container and nothing else.",
+        "A data-analysis agent executing generated Python in a microVM with the input dataset mounted read-only, no network at all and a wall-clock cap. The generated code can be wrong; it cannot be expensive or exfiltrating.",
+        "A document-processing agent that opens untrusted PDFs inside a disposable environment, because a parser exploit in an uploaded file is a real path to the host and the file arrived from outside."
+      ],
+      "kpis": [
+        {
+          "metric": "Share of executions sandboxed",
+          "note": "The coverage number. Anything running outside the sandbox is the actual security posture, regardless of what the sandboxed share does."
+        },
+        {
+          "metric": "Sandbox lifetime",
+          "note": "How long environments live. Rising lifetimes mean ephemerality is eroding into persistence."
+        },
+        {
+          "metric": "Resource-cap hits",
+          "note": "Tasks stopped by a quota or timeout. A useful mix of runaway generations and genuine limits set too tight."
+        },
+        {
+          "metric": "Secrets present at runtime",
+          "note": "Count of credentials reachable inside the environment. The target is the minimum the task needs, and often zero."
+        }
+      ],
+      "failureModes": [
+        "The convenience mount: a home directory, a credentials file or a socket mounted in so a task would stop failing.",
+        "Persistent reuse: the environment stops being per-task because rebuilding costs too much, so state and compromise both survive.",
+        "Open egress inside the boundary: strong isolation with a free network is containment against the filesystem only.",
+        "Orchestrator reachability: the sandbox can call the API that manages sandboxes, which is escape by design rather than by exploit."
+      ],
+      "lessons": [
+        "Isolate execution before you trust generation. The sandbox is what makes it reasonable to let an agent run code at all.",
+        "Ephemeral is the security property; isolation alone only postpones the problem.",
+        "The credential that is not present cannot be stolen — and it is the only control that holds after an escape.",
+        "Most sandbox activations are honest mistakes, not attacks. That is the pattern working, not evidence it was unnecessary."
+      ],
+      "faqs": [
+        {
+          "q": "Is a container enough, or do I need a microVM?",
+          "a": "It depends on what runs inside. For your own code with an injection risk, a hardened container with no credentials and constrained egress is usually proportionate. For arbitrary code from untrusted sources, assume the shared kernel can be escaped and use a microVM."
+        },
+        {
+          "q": "How does this differ from least-privilege tooling?",
+          "a": "Least privilege bounds what the agent may ask for; the sandbox bounds what happens when something runs anyway. One governs the request, the other the environment it executes in, and agents that run code need both."
+        },
+        {
+          "q": "The sandbox slows everything down. Is it worth it?",
+          "a": "Compare against the alternative cost, not against zero. Most of the latency is environment startup, which pools and pre-warmed images largely remove; the failure it prevents is a compromise of the host that runs the agent."
+        }
+      ]
+    },
+    "es": {
+      "name": "Ejecución en Sandbox",
+      "summary": "Ejecuta todo lo que un agente genera o invoca dentro de un entorno aislado y desechable, sin credenciales ambientales, con sistema de ficheros acotado, salida controlada y límites duros de recursos. El sandbox no está porque el agente sea malicioso, sino porque su entrada puede serlo.",
+      "definition": "La ejecución en sandbox es la práctica de correr el código generado por el agente y las acciones que invoca dentro de un entorno aislado y efímero cuyo sistema de ficheros, red, credenciales y recursos los acota el anfitrión y no el agente, de forma que un agente secuestrado o equivocado no pueda afectar a nada fuera de él.",
+      "problem": "Un agente que ejecuta código en el anfitrión hereda el anfitrión: sus credenciales, su sistema de ficheros, su posición de red. Una inyección con éxito o un comando confiadamente equivocado pasan entonces a ser indistinguibles de un compromiso de la máquina.",
+      "context": "Úsala siempre que un agente ejecute código, corra comandos de shell, instale paquetes o procese ficheros no confiables. El umbral es bajo: si el agente puede provocar ejecución, la ejecución va en un sandbox.",
+      "solution": [
+        "Hazlo efímero. Crea el entorno por tarea, destrúyelo al terminar y no arrastres estado que la siguiente tarea no haya pedido. La persistencia es cómo un compromiso puntual se convierte en punto de apoyo.",
+        "Elimina las credenciales ambientales. Nada del entorno debería ser utilizable solo por estar presente; inyecta únicamente los secretos acotados que la tarea necesita, durante lo que dure.",
+        "Acota el sistema de ficheros al conjunto de trabajo. Monta el repositorio o la entrada y nada más, y monta en solo lectura todo lo que no necesite escritura.",
+        "Restringe la salida dentro del sandbox, no alrededor. Desde el punto de vista del atacante el aislamiento y la política de red son el mismo control, y un sandbox con red abierta es una celda con teléfono.",
+        "Limita recursos: CPU, memoria, disco, tiempo de reloj, número de procesos. El consumo desbocado es el modo de fallo que llega primero y más a menudo, normalmente sin ningún adversario.",
+        "Registra lo que cruzó la frontera: qué ficheros entraron, cuáles salieron, a qué destinos se llegó. La frontera solo sirve si puedes ver qué pasó por ella."
+      ],
+      "components": [
+        "Una primitiva de aislamiento: contenedor, microVM o equivalente, elegida por la fuerza que la carga necesita.",
+        "Gestión de ciclo de vida efímero, con la destrucción como comportamiento por defecto y no como paso de limpieza.",
+        "Una vía de inyección de secretos acotada a la tarea y a su duración.",
+        "Una política de red aplicada dentro de la frontera del sandbox.",
+        "Cuotas de recursos y timeouts aplicados por el anfitrión.",
+        "Registro de frontera: entradas, salidas y destinos."
+      ],
+      "benefits": [
+        "Convierte «el agente ejecutó algo malo» de incidente en contenedor descartado.",
+        "Hace seguro dar a un agente capacidad real de ejecución, que suele ser justo lo que lo hace útil.",
+        "Acota los errores honestos igual que los ataques: el mismo control atrapa un bucle infinito y un payload inyectado.",
+        "Da un buen sitio donde observar: todo lo que la tarea tocó cruzó una única frontera."
+      ],
+      "risks": [
+        "Aislamiento más débil de lo supuesto: un kernel compartido no es una frontera de seguridad frente a un escape decidido, y tratar un contenedor como una microVM es un error de categoría.",
+        "Credenciales coladas por comodidad: un solo fichero de configuración montado deshace el patrón entero.",
+        "Sandboxes que se vuelven persistentes en silencio porque reconstruir es lento, y con ello desaparece la efimeridad que sostenía la garantía.",
+        "Escape por la superficie compartida que queda: volúmenes montados, la API del orquestador o la red a la que el sandbox sigue llegando."
+      ],
+      "whenNot": [
+        "Agentes de solo lectura sin capacidad de ejecución, donde no hay nada que aislar y el coste no compra nada.",
+        "Rutas en línea críticas en latencia donde el arranque del entorno domina la tarea y encaja mejor un control más estrecho: un intérprete restringido, una función pura.",
+        "Cuando el sandbox necesitaría justo las credenciales que existe para retener, que es señal de que la tarea hay que partirla en lugar de aislarla."
+      ],
+      "examples": [
+        "Un agente de programación que clona en un contenedor nuevo por tarea, con el repositorio montado, sin credenciales de nube presentes y con salida limitada al registro de paquetes. Una instalación de dependencia maliciosa destruye un contenedor y nada más.",
+        "Un agente de análisis de datos que ejecuta Python generado en una microVM con el dataset montado en solo lectura, sin red alguna y con límite de tiempo de reloj. El código generado puede estar mal; no puede salir caro ni exfiltrar.",
+        "Un agente de procesamiento documental que abre PDFs no confiables dentro de un entorno desechable, porque un exploit del parser en un fichero subido es una vía real al anfitrión y el fichero vino de fuera."
+      ],
+      "kpis": [
+        {
+          "metric": "Porcentaje de ejecuciones en sandbox",
+          "note": "El número de cobertura. Lo que corre fuera del sandbox es la postura de seguridad real, diga lo que diga la parte que sí está dentro."
+        },
+        {
+          "metric": "Vida del sandbox",
+          "note": "Cuánto duran los entornos. Vidas crecientes significan que la efimeridad se está erosionando hacia la persistencia."
+        },
+        {
+          "metric": "Choques con límites de recursos",
+          "note": "Tareas detenidas por una cuota o un timeout. Una mezcla útil de generaciones desbocadas y límites legítimos puestos demasiado estrechos."
+        },
+        {
+          "metric": "Secretos presentes en ejecución",
+          "note": "Número de credenciales alcanzables dentro del entorno. El objetivo es el mínimo que la tarea necesite, y a menudo cero."
+        }
+      ],
+      "failureModes": [
+        "El montaje por comodidad: un directorio home, un fichero de credenciales o un socket montados para que una tarea dejara de fallar.",
+        "Reutilización persistente: el entorno deja de ser por tarea porque reconstruir cuesta demasiado, así que sobreviven el estado y el compromiso.",
+        "Salida abierta dentro de la frontera: aislamiento fuerte con red libre es contención solo frente al sistema de ficheros.",
+        "Alcance al orquestador: el sandbox puede llamar a la API que gestiona sandboxes, lo que es escapar por diseño y no por exploit."
+      ],
+      "lessons": [
+        "Aísla la ejecución antes de confiar en la generación. El sandbox es lo que hace razonable dejar que un agente ejecute código.",
+        "Lo efímero es la propiedad de seguridad; el aislamiento por sí solo únicamente aplaza el problema.",
+        "La credencial que no está presente no se puede robar, y es el único control que aguanta después de un escape.",
+        "La mayoría de activaciones del sandbox son errores honestos, no ataques. Eso es el patrón funcionando, no la prueba de que sobraba."
+      ],
+      "faqs": [
+        {
+          "q": "¿Basta un contenedor o necesito una microVM?",
+          "a": "Depende de qué corre dentro. Para código propio con riesgo de inyección, un contenedor endurecido sin credenciales y con salida acotada suele ser proporcionado. Para código arbitrario de origen no confiable, asume que el kernel compartido se puede escapar y usa una microVM."
+        },
+        {
+          "q": "¿En qué se diferencia del mínimo privilegio en herramientas?",
+          "a": "El mínimo privilegio acota lo que el agente puede pedir; el sandbox acota lo que ocurre cuando algo se ejecuta igualmente. Uno gobierna la petición y el otro el entorno donde se ejecuta, y un agente que corre código necesita ambos."
+        },
+        {
+          "q": "El sandbox lo ralentiza todo, ¿compensa?",
+          "a": "Compáralo con el coste de la alternativa, no con cero. Casi toda la latencia es el arranque del entorno, que los pools y las imágenes precalentadas eliminan en buena parte; el fallo que evita es un compromiso del anfitrión que ejecuta el agente."
+        }
+      ]
+    },
+    "pt": {
+      "name": "Execução em Sandbox",
+      "summary": "Execute tudo o que um agente gera ou invoca dentro de um ambiente isolado e descartável, sem credenciais ambientais, com sistema de arquivos limitado, saída controlada e limites rígidos de recursos. O sandbox não existe porque o agente seja malicioso, mas porque a entrada dele pode ser.",
+      "definition": "Execução em sandbox é a prática de rodar o código gerado pelo agente e as ações que ele invoca dentro de um ambiente isolado e efêmero cujo sistema de arquivos, rede, credenciais e recursos são limitados pelo host e não pelo agente, de modo que um agente sequestrado ou equivocado não afete nada fora dele.",
+      "problem": "Um agente que executa código no host herda o host: suas credenciais, seu sistema de arquivos, sua posição de rede. Uma injeção bem-sucedida ou um comando confiantemente errado passam a ser indistinguíveis de um comprometimento da máquina.",
+      "context": "Use sempre que um agente executar código, rodar comandos de shell, instalar pacotes ou processar arquivos não confiáveis. O limiar é baixo: se o agente pode provocar execução, a execução vai para um sandbox.",
+      "solution": [
+        "Torne-o efêmero. Crie o ambiente por tarefa, destrua ao final e não carregue estado que a próxima tarefa não pediu. A persistência é como um comprometimento pontual vira ponto de apoio.",
+        "Remova as credenciais ambientais. Nada no ambiente deveria ser utilizável só por estar presente; injete apenas os segredos restritos de que a tarefa precisa, pelo tempo dela.",
+        "Limite o sistema de arquivos ao conjunto de trabalho. Monte o repositório ou a entrada e nada mais, e monte como somente leitura tudo o que não precisa de escrita.",
+        "Restrinja a saída dentro do sandbox, não em volta dele. Do ponto de vista do atacante, o isolamento e a política de rede são o mesmo controle, e um sandbox com rede aberta é uma cela com telefone.",
+        "Limite recursos: CPU, memória, disco, tempo de relógio, número de processos. O consumo descontrolado é o modo de falha que chega primeiro e com mais frequência, normalmente sem adversário algum.",
+        "Registre o que cruzou a fronteira: quais arquivos entraram, quais saíram, quais destinos foram alcançados. A fronteira só é útil se você puder ver o que passou por ela."
+      ],
+      "components": [
+        "Uma primitiva de isolamento: contêiner, microVM ou equivalente, escolhida pela força que a carga exige.",
+        "Gestão de ciclo de vida efêmero, com a destruição como comportamento padrão e não como etapa de limpeza.",
+        "Um caminho de injeção de segredos restrito à tarefa e à duração dela.",
+        "Uma política de rede aplicada dentro da fronteira do sandbox.",
+        "Cotas de recursos e timeouts aplicados pelo host.",
+        "Registro de fronteira: entradas, saídas e destinos."
+      ],
+      "benefits": [
+        "Converte «o agente executou algo ruim» de incidente em contêiner descartado.",
+        "Torna seguro dar a um agente capacidade real de execução, que costuma ser justamente o que o torna útil.",
+        "Limita erros honestos tanto quanto ataques: o mesmo controle pega um laço infinito e um payload injetado.",
+        "Dá um bom lugar para observar: tudo o que a tarefa tocou cruzou uma única fronteira."
+      ],
+      "risks": [
+        "Isolamento mais fraco do que o suposto: um kernel compartilhado não é fronteira de segurança contra um escape determinado, e tratar um contêiner como microVM é um erro de categoria.",
+        "Credenciais contrabandeadas por conveniência: um único arquivo de configuração montado desfaz o padrão inteiro.",
+        "Sandboxes que ficam persistentes em silêncio porque reconstruir é lento, e com isso some a efemeridade que sustentava a garantia.",
+        "Escape pela superfície compartilhada que resta: volumes montados, a API do orquestrador ou a rede que o sandbox ainda alcança."
+      ],
+      "whenNot": [
+        "Agentes somente leitura sem capacidade de execução, onde não há o que isolar e o custo não compra nada.",
+        "Caminhos em linha críticos em latência onde a inicialização do ambiente domina a tarefa e um controle mais estreito cabe melhor: um interpretador restrito, uma função pura.",
+        "Quando o sandbox precisaria justamente das credenciais que ele existe para reter, o que é sinal de que a tarefa deve ser dividida em vez de isolada."
+      ],
+      "examples": [
+        "Um agente de programação que clona em um contêiner novo por tarefa, com o repositório montado, sem credenciais de nuvem presentes e com saída limitada ao registry de pacotes. Uma instalação de dependência maliciosa destrói um contêiner e nada mais.",
+        "Um agente de análise de dados que executa Python gerado em uma microVM com o dataset montado somente leitura, sem rede alguma e com limite de tempo de relógio. O código gerado pode estar errado; não pode sair caro nem exfiltrar.",
+        "Um agente de processamento de documentos que abre PDFs não confiáveis dentro de um ambiente descartável, porque um exploit de parser em um arquivo enviado é um caminho real até o host e o arquivo veio de fora."
+      ],
+      "kpis": [
+        {
+          "metric": "Percentual de execuções em sandbox",
+          "note": "O número de cobertura. O que roda fora do sandbox é a postura de segurança real, independentemente do que a parte de dentro faça."
+        },
+        {
+          "metric": "Tempo de vida do sandbox",
+          "note": "Quanto duram os ambientes. Vidas crescentes significam que a efemeridade está erodindo para persistência."
+        },
+        {
+          "metric": "Batidas em limites de recursos",
+          "note": "Tarefas interrompidas por cota ou timeout. Uma mistura útil de gerações descontroladas e limites legítimos apertados demais."
+        },
+        {
+          "metric": "Segredos presentes em execução",
+          "note": "Número de credenciais alcançáveis dentro do ambiente. O alvo é o mínimo de que a tarefa precisa, e muitas vezes zero."
+        }
+      ],
+      "failureModes": [
+        "A montagem por conveniência: um diretório home, um arquivo de credenciais ou um socket montados para que uma tarefa parasse de falhar.",
+        "Reutilização persistente: o ambiente deixa de ser por tarefa porque reconstruir custa demais, então estado e comprometimento sobrevivem.",
+        "Saída aberta dentro da fronteira: isolamento forte com rede livre é contenção apenas contra o sistema de arquivos.",
+        "Alcance ao orquestrador: o sandbox consegue chamar a API que gerencia sandboxes, o que é escapar por design e não por exploit."
+      ],
+      "lessons": [
+        "Isole a execução antes de confiar na geração. O sandbox é o que torna razoável deixar um agente rodar código.",
+        "O efêmero é a propriedade de segurança; o isolamento sozinho apenas adia o problema.",
+        "A credencial que não está presente não pode ser roubada — e é o único controle que resiste depois de um escape.",
+        "A maioria das ativações do sandbox são erros honestos, não ataques. Isso é o padrão funcionando, não prova de que era desnecessário."
+      ],
+      "faqs": [
+        {
+          "q": "Um contêiner basta ou preciso de microVM?",
+          "a": "Depende do que roda dentro. Para código próprio com risco de injeção, um contêiner endurecido sem credenciais e com saída limitada costuma ser proporcional. Para código arbitrário de origem não confiável, assuma que o kernel compartilhado pode ser escapado e use uma microVM."
+        },
+        {
+          "q": "Em que difere de ferramentas com privilégio mínimo?",
+          "a": "O privilégio mínimo limita o que o agente pode pedir; o sandbox limita o que acontece quando algo executa mesmo assim. Um governa a requisição, o outro o ambiente em que ela roda, e agentes que executam código precisam dos dois."
+        },
+        {
+          "q": "O sandbox deixa tudo mais lento. Compensa?",
+          "a": "Compare com o custo da alternativa, não com zero. Quase toda a latência é a inicialização do ambiente, que pools e imagens pré-aquecidas removem em boa parte; a falha que ele evita é um comprometimento do host que roda o agente."
+        }
+      ]
+    }
+  }
+}