krnl-code 1.0.4__py3-none-any.whl

krnl_agent/mcp_client.py

@@ -0,0 +1,128 @@
+"""MCP (Model Context Protocol) client integration.
+
+Connects to external MCP servers (stdio or SSE/HTTP) and exposes their tools to
+the agent as OpenAI-style function schemas named ``mcp__<server>__<tool>``. This
+is the universal, model-independent extensibility layer: any MCP server's tools
+become available to whatever model you're running.
+
+Entirely optional and guarded: if the `mcp` package isn't installed or no servers
+are configured, this is a no-op and the core agent is unaffected.
+
+Config (config.yaml):
+    mcp:
+      servers:
+        filesystem:
+          command: npx
+          args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
+          env: {}
+        my_http:
+          url: https://example.com/mcp        # SSE endpoint
+"""
+from __future__ import annotations
+
+from contextlib import AsyncExitStack
+from typing import Any, Optional
+
+
+def mcp_available() -> bool:
+    try:
+        import mcp  # noqa: F401
+
+        return True
+    except Exception:
+        return False
+
+
+def _tool_name(server: str, tool: str) -> str:
+    return f"mcp__{server}__{tool}"
+
+
+class MCPManager:
+    def __init__(self, servers: dict):
+        self.servers = servers or {}
+        self._stack: Optional[AsyncExitStack] = None
+        self._sessions: dict[str, Any] = {}
+        self._schemas: list[dict] = []
+        self._route: dict[str, tuple[str, str]] = {}  # full name -> (server, tool)
+        self.errors: list[str] = []
+        self.started = False
+
+    def schemas(self) -> list[dict]:
+        return self._schemas
+
+    async def start(self) -> None:
+        if self.started or not self.servers or not mcp_available():
+            self.started = True
+            return
+        from mcp import ClientSession, StdioServerParameters
+        from mcp.client.stdio import stdio_client
+
+        self._stack = AsyncExitStack()
+        for name, conf in self.servers.items():
+            try:
+                if conf.get("url"):
+                    from mcp.client.sse import sse_client
+
+                    read, write = await self._stack.enter_async_context(
+                        sse_client(conf["url"])
+                    )
+                else:
+                    params = StdioServerParameters(
+                        command=conf["command"],
+                        args=conf.get("args", []),
+                        env=conf.get("env") or None,
+                    )
+                    read, write = await self._stack.enter_async_context(stdio_client(params))
+                session = await self._stack.enter_async_context(ClientSession(read, write))
+                await session.initialize()
+                self._sessions[name] = session
+                listed = await session.list_tools()
+                for t in listed.tools:
+                    full = _tool_name(name, t.name)
+                    self._route[full] = (name, t.name)
+                    self._schemas.append(
+                        {
+                            "type": "function",
+                            "function": {
+                                "name": full,
+                                "description": (t.description or "")[:1024],
+                                "parameters": t.inputSchema or {"type": "object", "properties": {}},
+                            },
+                        }
+                    )
+            except Exception as e:  # noqa: BLE001
+                self.errors.append(f"{name}: {e}")
+        self.started = True
+
+    async def call(self, full_name: str, args: dict) -> str:
+        route = self._route.get(full_name)
+        if not route:
+            return f"unknown MCP tool: {full_name}"
+        server, tool = route
+        session = self._sessions.get(server)
+        if not session:
+            return f"MCP server not connected: {server}"
+        try:
+            result = await session.call_tool(tool, args or {})
+        except Exception as e:  # noqa: BLE001
+            return f"MCP tool error: {e}"
+        # result.content is a list of content blocks
+        parts: list[str] = []
+        for block in getattr(result, "content", []) or []:
+            text = getattr(block, "text", None)
+            parts.append(text if text is not None else str(block))
+        return "\n".join(parts) if parts else "(no content)"
+
+    async def stop(self) -> None:
+        if self._stack:
+            try:
+                await self._stack.aclose()
+            except Exception:
+                pass
+            self._stack = None
+        self._sessions.clear()
+        self.started = False
+
+
+def is_mcp_tool(name: str) -> bool:
+    return name.startswith("mcp__")

krnl_agent/memory.py

@@ -0,0 +1,61 @@
+"""Project & user memory — persistent instructions auto-loaded into context.
+
+Looks for memory files in the workspace (and a global one) and injects them into
+the system prompt, so project conventions and standing instructions are always in
+context (like Claude Code's CLAUDE.md / AGENTS.md).
+
+Precedence (all concatenated): user-global → project.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .settings import SETTINGS_DIR
+
+PROJECT_FILES = ["AGENTS.md", "KRNL.md", "CLAUDE.md", ".krnl/AGENTS.md"]
+USER_FILE = SETTINGS_DIR / "AGENTS.md"
+_MAX = 12000
+
+
+def load_memory(workspace: str) -> str:
+    parts: list[str] = []
+    if USER_FILE.is_file():
+        try:
+            parts.append("# User memory (global)\n" + USER_FILE.read_text(encoding="utf-8")[:_MAX])
+        except Exception:
+            pass
+    root = Path(workspace)
+    for name in PROJECT_FILES:
+        p = root / name
+        if p.is_file():
+            try:
+                parts.append(f"# Project memory ({name})\n" + p.read_text(encoding="utf-8")[:_MAX])
+            except Exception:
+                pass
+            break  # first project memory file wins
+    return "\n\n".join(parts)
+
+
+TEMPLATE = """# Project memory for the Krnl Agent
+
+This file is automatically loaded into the agent's context. Put standing
+instructions and project conventions here.
+
+## Commands
+- Build:
+- Test:
+- Lint:
+
+## Conventions
+- (e.g. "use 4-space indent", "prefer async", "never touch generated/")
+
+## Notes
+- (anything the agent should always know about this project)
+"""
+
+
+def write_template(workspace: str) -> Path:
+    path = Path(workspace) / "AGENTS.md"
+    if not path.exists():
+        path.write_text(TEMPLATE, encoding="utf-8")
+    return path

krnl_agent/modelrouter.py

@@ -0,0 +1,151 @@
+"""Multi-model routing — one model per job, across providers, cost-aware.
+
+You can assign a different model (from any configured provider) to each *phase* of
+the agent's work:
+
+    models:                       # named roles; each may be a different provider
+      planner:  { provider: anthropic, model: claude-opus-4-8 }
+      executor: { provider: openai,    model: gpt-5.5 }
+      cheap:    { provider: groq,      model: llama-3.3-70b-versatile }
+      verifier: { provider: gemini,    model: gemini-2.5-flash }
+    routing:
+      strategy: auto              # auto = cheap-where-safe + escalate on trouble
+      plan: planner               # model used in plan mode
+      execute: executor           # model for normal execution
+      subagent: cheap             # model for delegated sub-agents
+      verify: cheap               # model for the post-edit verifier
+      escalate: planner           # stronger model to jump to when quality slips
+      escalate_after: 2           # consecutive all-failed steps before escalating
+
+The goal is to spend the least money that still gets the job done: cheap models for
+mechanical / parallel work, your main model for execution, a strong reasoning model
+for planning — and an automatic **escalation** to a stronger model when the cheaper
+one keeps failing. If nothing is configured, behaviour is identical to before
+(single active model, with `router.cheap` / `subagent_model` still honored).
+"""
+from __future__ import annotations
+
+from dataclasses import replace
+
+from . import pricing
+from .config import AgentConfig, Config, ProviderConfig
+from .llm import build_client
+
+# Phase -> ordered fallback role names if the phase isn't explicitly routed.
+_PHASE_DEFAULTS = {
+    "plan": ["planner", "plan", "heavy", "executor", "execute"],
+    "execute": ["executor", "execute"],
+    "subagent": ["subagent", "cheap", "executor", "execute"],
+    "verify": ["verifier", "verify", "cheap", "executor", "execute"],
+    "escalate": ["escalate", "heavy", "planner", "executor", "execute"],
+}
+
+
+class ModelRouter:
+    def __init__(self, config: Config):
+        self.config = config
+        self.routing: dict = dict(config.routing or {})
+        self.strategy = str(self.routing.get("strategy", "auto")).lower()
+        self.escalate_after = int(self.routing.get("escalate_after", 2))
+        self.roles: dict[str, dict] = self._build_roles()
+        self._clients: dict[str, object] = {}
+
+    # --- role resolution -------------------------------------------------- #
+    def _build_roles(self) -> dict[str, dict]:
+        roles: dict[str, dict] = {}
+        for name, entry in (self.config.models or {}).items():
+            if isinstance(entry, str):          # shorthand: "role: model-id"
+                entry = {"model": entry}
+            roles[name] = dict(entry or {})
+        # Implicit roles for back-compat / zero-config.
+        roles.setdefault("execute", {"provider": self.config.provider.name,
+                                     "model": self.config.provider.model})
+        roles.setdefault("executor", roles["execute"])
+        cheap = (self.config.router or {}).get("cheap") or self.config.subagent_model
+        if cheap and "cheap" not in roles:
+            roles["cheap"] = {"model": cheap}
+        heavy = (self.config.router or {}).get("heavy")
+        if heavy and "heavy" not in roles:
+            roles["heavy"] = {"model": heavy}
+        return roles
+
+    def role_for_phase(self, phase: str) -> str:
+        explicit = self.routing.get(phase)
+        if explicit and explicit in self.roles:
+            return explicit
+        for cand in _PHASE_DEFAULTS.get(phase, ["execute"]):
+            if cand in self.roles:
+                return cand
+        return "execute"
+
+    def _provider_for_role(self, role: str) -> ProviderConfig:
+        entry = self.roles.get(role, {})
+        base_name = entry.get("provider") or self.config.provider.name
+        # Prefer the live active provider (it may carry a runtime-injected key).
+        if base_name == self.config.provider.name:
+            base = self.config.provider
+        else:
+            base = self.config.all_providers.get(base_name, self.config.provider)
+        over: dict = {}
+        if entry.get("model"):
+            over["model"] = entry["model"]
+        if "temperature" in entry:
+            over["temperature"] = float(entry["temperature"])
+        if "max_tokens" in entry:
+            over["max_tokens"] = int(entry["max_tokens"])
+        return replace(base, **over) if over else base
+
+    def _agent_for_role(self, role: str) -> AgentConfig:
+        entry = self.roles.get(role, {})
+        if "fallback_models" in entry:
+            return replace(self.config.agent, fallback_models=list(entry["fallback_models"]))
+        return self.config.agent
+
+    # --- public API ------------------------------------------------------- #
+    def provider_for_phase(self, phase: str) -> ProviderConfig:
+        return self._provider_for_role(self.role_for_phase(phase))
+
+    def model_for_phase(self, phase: str) -> str:
+        return self.provider_for_phase(phase).model
+
+    def client_for_phase(self, phase: str):
+        role = self.role_for_phase(phase)
+        if role not in self._clients:
+            self._clients[role] = build_client(self._provider_for_role(role),
+                                               self._agent_for_role(role))
+        return self._clients[role]
+
+    def is_default_phase(self, phase: str) -> bool:
+        """True if `phase` resolves to the active provider's model (no divergence).
+        Lets callers reuse an injected/active client instead of building a new one."""
+        p = self.provider_for_phase(phase)
+        return p.name == self.config.provider.name and p.model == self.config.provider.model
+
+    def has_distinct_escalation(self) -> bool:
+        """True if the escalate phase resolves to a different model than execute."""
+        return self.model_for_phase("escalate") != self.model_for_phase("execute")
+
+    @staticmethod
+    def _blended_rate(model: str, overrides: dict | None = None) -> float | None:
+        r = pricing.rate_for(model, overrides)
+        if r is None:
+            return None
+        # Weight output heavier (it dominates agent cost): input + 3*output.
+        return r[0] + 3 * r[1]
+
+    def summary(self) -> list[dict]:
+        """One row per phase: which role/provider/model and its price (visibility)."""
+        rows = []
+        for phase in ("plan", "execute", "subagent", "verify", "escalate"):
+            role = self.role_for_phase(phase)
+            p = self._provider_for_role(role)
+            rate = pricing.rate_for(p.model, self.config.pricing)
+            rows.append({
+                "phase": phase,
+                "role": role,
+                "provider": p.name,
+                "model": p.model,
+                "in_per_1m": rate[0] if rate else None,
+                "out_per_1m": rate[1] if rate else None,
+            })
+        return rows

krnl_agent/monitor.py

@@ -0,0 +1,112 @@
+"""Runtime monitoring & observability wiring.
+
+The missing pillar in the field: once an app is deployed, give it eyes. This module
+helps the agent (1) instrument the app with error tracking + telemetry, (2) make sure
+a health endpoint exists, (3) register an uptime check, and (4) report current status
+back into the terminal. Everything is credential-by-env-var and network calls are
+best-effort (skipped cleanly when a token isn't set).
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+# Health-endpoint snippets the agent can drop into a project that lacks one.
+HEALTH_SNIPPETS = {
+    "fastapi": (
+        '@app.get("/health")\n'
+        'def health():\n'
+        '    return {"status": "ok"}\n'),
+    "flask": (
+        '@app.get("/health")\n'
+        'def health():\n'
+        '    return {"status": "ok"}, 200\n'),
+    "express": (
+        "app.get('/health', (req, res) => res.json({ status: 'ok' }));\n"),
+    "next": (
+        "// app/health/route.ts\n"
+        "export function GET() { return Response.json({ status: 'ok' }); }\n"),
+}
+
+
+def instrument_env() -> dict[str, str]:
+    """Env vars to inject into the deployed service for monitoring, based on what the
+    user has configured locally. Only includes a var if its source is present."""
+    out: dict[str, str] = {}
+    if os.getenv("SENTRY_DSN"):
+        out["SENTRY_DSN"] = os.environ["SENTRY_DSN"]
+    if os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT"):
+        out["OTEL_EXPORTER_OTLP_ENDPOINT"] = os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"]
+        if os.getenv("OTEL_EXPORTER_OTLP_HEADERS"):
+            out["OTEL_EXPORTER_OTLP_HEADERS"] = os.environ["OTEL_EXPORTER_OTLP_HEADERS"]
+    return out
+
+
+def configured_providers() -> dict[str, bool]:
+    return {
+        "sentry": bool(os.getenv("SENTRY_DSN") or os.getenv("SENTRY_AUTH_TOKEN")),
+        "opentelemetry": bool(os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")),
+        "datadog": bool(os.getenv("DD_API_KEY")),
+        "uptimerobot": bool(os.getenv("UPTIMEROBOT_API_KEY")),
+        "betterstack": bool(os.getenv("BETTERSTACK_TOKEN")),
+    }
+
+
+def register_uptime_command(url: str) -> tuple[bool, str]:
+    """Build a headless command to register an uptime monitor for `url`."""
+    if os.getenv("UPTIMEROBOT_API_KEY"):
+        return True, (
+            'curl -s -X POST https://api.uptimerobot.com/v3/monitors '
+            '-H "Authorization: Bearer $UPTIMEROBOT_API_KEY" '
+            '-H "Content-Type: application/json" '
+            f'-d \'{{"type":"http","url":"{url}","interval":300,"friendlyName":"krnl"}}\'')
+    if os.getenv("BETTERSTACK_TOKEN"):
+        return True, (
+            'curl -s -X POST https://uptime.betterstack.com/api/v2/monitors '
+            '-H "Authorization: Bearer $BETTERSTACK_TOKEN" '
+            '-H "Content-Type: application/json" '
+            f'-d \'{{"monitor_type":"status","url":"{url}"}}\'')
+    return False, ("No uptime provider configured. Set UPTIMEROBOT_API_KEY or "
+                   "BETTERSTACK_TOKEN to auto-register a check.")
+
+
+def _sentry_unresolved() -> tuple[int, list[str]] | None:
+    """Best-effort: count unresolved Sentry issues. Returns None if not configured
+    or the call fails (never raises)."""
+    token = os.getenv("SENTRY_AUTH_TOKEN")
+    org = os.getenv("SENTRY_ORG")
+    project = os.getenv("SENTRY_PROJECT")
+    if not (token and org and project):
+        return None
+    url = (f"https://sentry.io/api/0/projects/{org}/{project}/issues/"
+           "?query=is:unresolved&statsPeriod=24h")
+    try:
+        req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+        with urllib.request.urlopen(req, timeout=10) as r:  # noqa: S310
+            data = json.loads(r.read().decode("utf-8"))
+        titles = [i.get("title", "?") for i in data[:5]]
+        return len(data), titles
+    except (urllib.error.URLError, ValueError, TimeoutError, Exception):  # noqa: BLE001
+        return None
+
+
+def status() -> str:
+    """Human-readable monitoring status for the `monitor` command."""
+    prov = configured_providers()
+    lines = ["Monitoring status", ""]
+    for name, on in prov.items():
+        lines.append(f"  {'✔' if on else '○'} {name}: {'configured' if on else 'not set'}")
+    sentry = _sentry_unresolved()
+    if sentry is not None:
+        n, titles = sentry
+        lines += ["", f"Sentry: {n} unresolved issue(s) in the last 24h:"]
+        lines += [f"  - {t}" for t in titles] or ["  (none)"]
+    elif prov["sentry"]:
+        lines += ["", "Sentry: set SENTRY_AUTH_TOKEN + SENTRY_ORG + SENTRY_PROJECT to "
+                  "pull live issues."]
+    if not any(prov.values()):
+        lines += ["", "No monitoring configured yet. `krnl-agent ship` wires Sentry/OTel "
+                  "+ an uptime check automatically when their tokens are present."]
+    return "\n".join(lines)

krnl_agent/notify.py

@@ -0,0 +1,119 @@
+"""Messaging connectors — push agent results to Slack / Discord / Telegram.
+
+Config (config.yaml):
+    notifications:
+      on: [done, error]          # which events to notify on
+      slack_webhook: https://hooks.slack.com/services/...
+      discord_webhook: https://discord.com/api/webhooks/...
+      telegram_token: 123:ABC
+      telegram_chat_id: "123456"
+
+Used by the loop (on task completion) and by scheduled agents.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+
+def send_slack(webhook: str, text: str) -> bool:
+    import httpx
+
+    try:
+        r = httpx.post(webhook, json={"text": text}, timeout=15)
+        return r.status_code < 300
+    except Exception:
+        return False
+
+
+def send_discord(webhook: str, text: str) -> bool:
+    import httpx
+
+    try:
+        r = httpx.post(webhook, json={"content": text[:1900]}, timeout=15)
+        return r.status_code < 300
+    except Exception:
+        return False
+
+
+def send_telegram(token: str, chat_id: str, text: str) -> bool:
+    import httpx
+
+    try:
+        r = httpx.post(
+            f"https://api.telegram.org/bot{token}/sendMessage",
+            json={"chat_id": chat_id, "text": text[:4000]},
+            timeout=15,
+        )
+        return r.status_code < 300
+    except Exception:
+        return False
+
+
+def send_google_chat(webhook: str, text: str) -> bool:
+    import httpx
+
+    try:
+        r = httpx.post(webhook, json={"text": text[:4000]}, timeout=15)
+        return r.status_code < 300
+    except Exception:
+        return False
+
+
+def send_whatsapp(sid: str, token: str, frm: str, to: str, text: str) -> bool:
+    """Send a WhatsApp message via Twilio."""
+    import httpx
+
+    try:
+        r = httpx.post(
+            f"https://api.twilio.com/2010-04-01/Accounts/{sid}/Messages.json",
+            data={"From": f"whatsapp:{frm}", "To": f"whatsapp:{to}", "Body": text[:1500]},
+            auth=(sid, token),
+            timeout=15,
+        )
+        return r.status_code < 300
+    except Exception:
+        return False
+
+
+def send_linear(api_key: str, team_id: str, text: str) -> bool:
+    """Create a Linear issue with the result."""
+    import httpx
+
+    mutation = (
+        "mutation($t:String!,$d:String!,$team:String!){"
+        "issueCreate(input:{teamId:$team,title:$t,description:$d}){success}}"
+    )
+    try:
+        r = httpx.post(
+            "https://api.linear.app/graphql",
+            json={"query": mutation, "variables": {
+                "t": text.splitlines()[0][:80] or "Krnl Agent", "d": text[:4000], "team": team_id}},
+            headers={"Authorization": api_key, "Content-Type": "application/json"},
+            timeout=15,
+        )
+        return r.status_code < 300
+    except Exception:
+        return False
+
+
+def dispatch(config: Optional[dict], text: str) -> list[str]:
+    """Send `text` to every configured channel. Returns the channels notified."""
+    config = config or {}
+    sent = []
+    if config.get("slack_webhook") and send_slack(config["slack_webhook"], text):
+        sent.append("slack")
+    if config.get("discord_webhook") and send_discord(config["discord_webhook"], text):
+        sent.append("discord")
+    if config.get("telegram_token") and config.get("telegram_chat_id"):
+        if send_telegram(config["telegram_token"], str(config["telegram_chat_id"]), text):
+            sent.append("telegram")
+    if config.get("google_chat_webhook") and send_google_chat(config["google_chat_webhook"], text):
+        sent.append("google_chat")
+    if all(config.get(k) for k in ("twilio_sid", "twilio_token", "whatsapp_from", "whatsapp_to")):
+        if send_whatsapp(config["twilio_sid"], config["twilio_token"],
+                         str(config["whatsapp_from"]), str(config["whatsapp_to"]), text):
+            sent.append("whatsapp")
+    if config.get("linear_api_key") and config.get("linear_team_id"):
+        if send_linear(config["linear_api_key"], config["linear_team_id"], text):
+            sent.append("linear")
+    return sent