Architecture

How kprompt works: intent compiler pipeline, AI SRE CLI vs Observe agent, modes, and honesty boundaries — in diagrams.

Intent compiler

kprompt is not a chat REPL that pipes model output to bash. A prompt becomes a typed Intent, then a PlanResult with actions, risk, and blast radius. Safety hard-denies wipe-class intents. Apply only after TTY confirmation or --approve.

Intent compiler

Natural language becomes a reviewable PlanResult. Nothing mutates until you approve.

  1. 01PromptPlain English
  2. 02IntentTyped schema
  3. 03PlanActions + diffs
  4. 04SafetyHard deny + risk
  5. 05ApproveTTY y/N or --approve
  6. 06Applyclient-go SSA

AI SRE dual path

On-demand CLI packs (investigate, why, timeline, …) and the optional in-cluster agent share the same incident contracts. One is reactive; the other is always-on. Neither is silent Autopilot.

AI SRE — two surfaces, one contract

Reactive CLI intelligence and the optional in-cluster agent share Investigation / Incident types. Neither silently mutates.

On demand · laptop

AI SRE CLI

You ask. kprompt walks Service → Endpoints → Deploy → Pods → Events → Logs and returns a typed artifact.

  • investigateInvestigation
  • whyCause findings
  • timelineOrdered events
  • impactBlast radius
  • audit / driftHygiene · sync

Same PlanResult path if a fix is suggested.

Always on · in-cluster

Observe / Namespace Agent

Helm (or Operator) deploys a Role-scoped watcher. Correlates Incidents, analyzes once per window, notifies with confidence.

  • ObserveNever

    Watch → Incident → gated alert

  • Namespace AgentPropose-first

    RCA · memory · report v2 · learn

  • CoordinatorOff by default

    Cross-ns handoff fan-in

  • AutopilotpolicyAuto only

    Allowlisted remediations

Same binary: kprompt agent run

Shared core: internal/incident — Investigation · Incident · AgentAlert · InvestigationReport

Observe agent pipeline

Default mode watches one namespace with a Role (not ClusterRole), correlates into Incidents, builds context, analyzes once per window, then gates Slack/webhook on severity and confidence. Install guide: Observe agent.

Observe agent pipeline

Always-on, namespace-scoped. Batches by open Incident — not one LLM call per raw event. Mutate stays off.

  1. 01WatchPods · Events · …
  2. 02NormalizeTyped signals
  3. 03DedupeBurst collapse
  4. 04IncidentCorrelate window
  5. 05ContextLogs · metrics · GitOps
  6. 06AnalyzeLLM or --heuristic
  7. 07GateSeverity · confidence
  8. 08NotifySlack / webhook

Modes

Observe never mutates. Namespace Agent adds multi-signal RCA, memory/patterns, and InvestigationReport v2 — still propose-first. Coordinator only verifies cross-namespace suspicion. Autopilot apply requires an explicit policy allowlist.

Modes at a glance

Namespace Agent is not a new binary — it is the Observe runtime with RCA, memory, and handoff under ADR-0016.

SurfaceScopeArtifactMutate?
CLIkubeconfigPlanResultAfter approve
ObserveOne namespaceIncident / AlertNever
Namespace AgentOne namespaceReport v2Propose-first
CoordinatorCross-nsHandoffDefault off

Coordinator handoff

Cross-namespace suspicion is a handoff, not a god-mode agent.

  1. 01Namespace Agent→ Slack · webhook · ask →Humans / SIEM

    InvestigationReport v2 — read path

  2. 02Namespace Agent→ CoordinatorHandoff →Coordinator

    Suspect outside my ns? Hand off — don’t invent cross-ns root cause

  3. 03Coordinator→ CoordinatorReply →Namespace Agent

    Thin verify / fan-in. Mutate stays off by default

Honesty boundaries

  • No silent or default LLM-said-so remediations
  • No cluster-wide god-mode SA on every namespace agent
  • Missing Prom / OTel / GitOps backends degrade — they are not invented
  • Memory and patterns boost confidence; they are not sole proof of root cause
  • Not feature parity with K8sGPT (fleet scanner) or Kagent (multi-agent framework)

Positioning and shipped vs building: Roadmap & vision. Series: Building AI SRE in Public.