agentkernel-cli 0.1.0__py3-none-any.whl

agentkernel/__init__.py

@@ -0,0 +1,7 @@
+"""agentkernel — a minimal, dependency-light kernel for a general-purpose AI agent.
+
+The kernel runs the agent loop (model -> tool calls -> results -> repeat) and
+nothing more. See `agent-kernel-design.md` for the full specification.
+"""
+
+__version__ = "0.0.1"

agentkernel/__main__.py

@@ -0,0 +1,5 @@
+"""Enable ``python -m agentkernel`` (used for detached background runs)."""
+
+from agentkernel.cli import main
+
+raise SystemExit(main())

agentkernel/agent.py

@@ -0,0 +1,311 @@
+"""The agent loop (design §7).
+
+This reads like the pseudocode in the design doc on purpose: no clever
+metaprogramming, no provider-specific branching. The loop sends the context
+window plus tools to the provider, parses any tool calls out of the response,
+executes them through the registry (gating mutations through the approver), and
+appends every result back, paired to its call id (design §8), until the model
+produces a final answer.
+"""
+
+from __future__ import annotations
+
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from typing import TYPE_CHECKING, Any
+
+from agentkernel.budget import BudgetGuard
+from agentkernel.context import ContextManager
+from agentkernel.context.truncate import truncate_text
+from agentkernel.redaction import redact_secrets
+from agentkernel.telemetry import ToolOutcome
+from agentkernel.types import Message, ToolResult
+
+if TYPE_CHECKING:
+    from agentkernel.approval import Approver
+    from agentkernel.config import Config
+    from agentkernel.memory import MemoryStore, NoteStore
+    from agentkernel.providers import Provider
+    from agentkernel.skills import ContextSource
+    from agentkernel.telemetry import Telemetry
+    from agentkernel.tools import ToolRegistry, ToolSpec
+    from agentkernel.types import ToolCall
+
+
+class Agent:
+    """Orchestrates one conversation. All collaborators are injected (no global
+    state), so ``run`` is re-entrant: a tool handler may construct another Agent
+    and call ``run`` to spawn a sub-agent (design §7, §13)."""
+
+    def __init__(
+        self,
+        provider: Provider,
+        registry: ToolRegistry,
+        context: ContextManager,
+        approver: Approver,
+        telemetry: Telemetry,
+        config: Config,
+        budget: BudgetGuard | None = None,
+        memory: MemoryStore | None = None,
+        notes: NoteStore | None = None,
+        context_source: ContextSource | None = None,
+    ) -> None:
+        self.provider = provider
+        self.registry = registry
+        self.context = context
+        self.approver = approver
+        self.telemetry = telemetry
+        self.config = config
+        self.budget = budget
+        self.memory = memory
+        self.notes = notes
+        self.context_source = context_source
+
+    def run(
+        self,
+        user_input: str,
+        *,
+        profile: Any | None = None,
+        on_text: Any | None = None,
+    ) -> str:
+        """Drive the loop until a final answer or the max-iteration guard.
+
+        ``profile`` (design §13, Phase 5) is accepted but, in the kernel, only
+        ``tool_filter`` / ``system_prompt`` are honored if trivially present.
+        ``on_text`` (when set) receives streamed text deltas; the loop contract is
+        otherwise unchanged.
+        """
+        session_id = getattr(self.telemetry, "session_id", str(uuid.uuid4()))
+
+        # Pre-run memory load (Phase 3). Only load when context is empty so a
+        # persistent REPL session does not replay the same stored turns twice.
+        if self.memory is not None and not self.context.messages():
+            for message in self.memory.load(session_id):
+                self.context.add(message)
+
+        self.context.add(
+            Message(role="user", content=self._prepare_user_message(user_input))
+        )
+
+        # Assemble the cacheable prefix ONCE per run and reuse the same objects
+        # every turn. Re-building or re-sorting these per turn would silently
+        # destroy prompt-cache hit-rate (design §9.3, AGENT.md rule 3).
+        tools = self._tools_for(profile)
+        system = self._system_for(profile)
+        reasoning = getattr(profile, "reasoning", None)
+        provider = self._provider_for(profile)  # honor profile.model_override
+
+        if self.budget is not None:
+            self.budget.reset()
+
+        for iteration in range(self.config.max_iterations):
+            messages = self.context.window()  # compacted to budget in M2
+
+            resp = provider.complete(
+                messages,
+                tools,
+                max_tokens=self.config.max_output_tokens,
+                system=system,
+                reasoning=reasoning,
+                on_text=on_text,
+            )
+            self.context.add(resp.message)
+            compaction = self.context.take_compaction()
+
+            if self.budget is not None:
+                self.budget.add(resp.usage)
+                exceeded, reason = self.budget.exceeded()
+                if exceeded:
+                    # The token spend already happened; record it, then either
+                    # return the final answer (if we have one) or stop early.
+                    self.telemetry.record_turn(iteration, resp, compaction=compaction)
+                    if not resp.message.tool_calls:
+                        self._persist_memory(session_id)
+                        return resp.message.content
+                    self._persist_memory(session_id)
+                    return f"Stopped: budget exceeded ({reason})."
+
+            if not resp.message.tool_calls:
+                self.telemetry.record_turn(iteration, resp, compaction=compaction)
+                self._persist_memory(session_id)
+                return resp.message.content  # final answer
+
+            tool_calls = resp.message.tool_calls
+            specs = [self.registry.spec(call.name) for call in tool_calls]
+            validation_errors = [self.registry.validate(call) for call in tool_calls]
+
+            if self.config.plan_mode and not self._approve_plan(tool_calls, specs):
+                self.telemetry.record_turn(
+                    iteration, resp, tool_outcomes=[], compaction=compaction
+                )
+                self._persist_memory(session_id)
+                return "Plan denied by user."
+
+            # Validate + approve sequentially so interactive approval prompts
+            # stay ordered and un-interleaved; then execute the approved calls,
+            # concurrently when ``config.tool_concurrency > 1`` (design §7 said
+            # the structure must allow concurrency — this is it). Results are
+            # placed back by index so §8 pairing and ordering are preserved.
+            results: list[ToolResult] = [None] * len(tool_calls)  # type: ignore[list-item]
+            outcomes: list[ToolOutcome] = [None] * len(tool_calls)  # type: ignore[list-item]
+            pending: list[int] = []
+            for idx, (call, spec, err) in enumerate(
+                zip(tool_calls, specs, validation_errors, strict=True)
+            ):
+                if err:
+                    results[idx] = ToolResult(call.id, err, is_error=True)
+                    outcomes[idx] = ToolOutcome(call.name, call.arguments, None, True)
+                elif (
+                    not self.config.plan_mode
+                    and self._needs_approval(spec)
+                    and not self.approver.approve(call, spec)
+                ):
+                    results[idx] = ToolResult(call.id, "Denied by user.", is_error=True)
+                    outcomes[idx] = ToolOutcome(call.name, call.arguments, False, True)
+                else:
+                    pending.append(idx)
+
+            def _execute(idx: int, _calls=tool_calls) -> tuple[int, ToolResult]:
+                return idx, self.registry.execute(_calls[idx])
+
+            concurrency = max(1, getattr(self.config, "tool_concurrency", 1))
+            if concurrency > 1 and len(pending) > 1:
+                with ThreadPoolExecutor(max_workers=min(concurrency, len(pending))) as pool:
+                    executed = list(pool.map(_execute, pending))
+            else:
+                executed = [_execute(idx) for idx in pending]
+            for idx, result in executed:
+                call = tool_calls[idx]
+                results[idx] = result
+                outcomes[idx] = ToolOutcome(
+                    call.name, call.arguments, True, result.is_error
+                )
+
+            # Scrub secrets, then cap every result before it enters context
+            # (design §8.4, §18.1). This is the single processing point for all
+            # tools — builtin and future. Redaction runs on the full content
+            # (before truncation, so a secret can't be split past the cap), and
+            # structured `data` is left intact.
+            redact = getattr(self.config, "redact_tool_output", True)
+            for r in results:
+                if redact:
+                    r.content, _ = redact_secrets(r.content)
+                r.content = truncate_text(r.content, self.config.max_tool_result_tokens)
+
+            self.telemetry.record_turn(
+                iteration, resp, tool_outcomes=outcomes, compaction=compaction
+            )
+
+            # One tool-role message carries every result, paired to its call id.
+            # The adapter fans this out to the provider's shape (design §8.1).
+            self.context.add(Message(role="tool", tool_results=results))
+
+        self._persist_memory(session_id)
+        return "Stopped: reached max iterations without a final answer."
+
+    # --- memory helper ------------------------------------------------------
+
+    def _persist_memory(self, session_id: str) -> None:
+        if self.memory is not None:
+            self.memory.save(session_id, self._messages_for_storage())
+
+    def _messages_for_storage(self) -> list[Message]:
+        """Return the conversation, compacted if a persistence budget is set.
+
+        This applies the same deterministic compaction the main context uses,
+        but with a separate ``memory_store_budget`` tuned for on-disk recall.
+        Keeping only a summary plus recent turns keeps the store lightweight.
+        """
+        messages = self.context.messages()
+        budget = getattr(self.config, "memory_store_budget", None)
+        if budget is None or budget <= 0:
+            return messages
+        cm = ContextManager(budget=budget)
+        for m in messages:
+            cm.add(m)
+        return cm.window()
+
+    def _prepare_user_message(self, user_input: str) -> str:
+        """Augment the user input with relevant long-term memory when configured.
+
+        This keeps memory at the model's fingertips for the current turn without
+        changing the stable system-prompt prefix.
+        """
+        if not user_input or not self.notes or not getattr(
+            self.config, "memory_auto_context", False
+        ):
+            return user_input
+        limit = getattr(self.config, "memory_auto_context_limit", 3)
+        try:
+            notes = self.notes.search(user_input, limit=limit)
+        except Exception:  # noqa: BLE001 - best-effort recall must not crash the run
+            # Auto-context is a convenience layered before the loop. If recall
+            # fails (embedding endpoint down, API key missing, store error), fall
+            # back to the plain user input rather than taking down the session.
+            return user_input
+        if not notes:
+            return user_input
+        lines = ["Relevant long-term memory:"]
+        for n in notes:
+            lines.append(f"- {n.text}")
+        lines.append("---")
+        lines.append(user_input)
+        return "\n".join(lines)
+
+    # --- profile seams (design §13, Phase 5) -------------------------------
+
+    def _tools_for(self, profile: Any | None) -> list[ToolSpec]:
+        """The tool set for this run. Stable across turns to keep the prefix
+        cacheable (design §9.3): assembled from the registry's registration
+        order and not re-sorted."""
+        specs = self.registry.specs()
+        tool_filter = getattr(profile, "tool_filter", None)
+        if tool_filter is not None:
+            allowed = set(tool_filter)
+            specs = [s for s in specs if s.name in allowed]
+        return specs
+
+    def _provider_for(self, profile: Any | None):
+        """Honor ``profile.model_override`` for this run (design §13, Phase 5).
+
+        Returns a copy of the provider bound to the override model when set and
+        the provider supports ``with_model``; otherwise the injected provider."""
+        override = getattr(profile, "model_override", None)
+        if (
+            override
+            and override != getattr(self.provider, "model", None)
+            and hasattr(self.provider, "with_model")
+        ):
+            return self.provider.with_model(override)
+        return self.provider
+
+    def _system_for(self, profile: Any | None) -> str | None:
+        """Combine profile system prompt and active skill additions.
+
+        The cacheable prefix stays stable because tools and system Prompt are
+        assembled once per run.
+        """
+        parts: list[str] = []
+        profile_prompt = getattr(profile, "system_prompt", None)
+        if profile_prompt:
+            parts.append(profile_prompt)
+        if self.context_source is not None:
+            parts.extend(self.context_source.system_additions())
+        if not parts:
+            return None
+        return "\n\n".join(parts)
+
+    @staticmethod
+    def _needs_approval(spec: ToolSpec | None) -> bool:
+        return bool(spec and spec.gated)
+
+    def _approve_plan(
+        self, calls: list[ToolCall], specs: list[ToolSpec | None]
+    ) -> bool:
+        """Ask the approver for the whole batch; fall back to per-call approval."""
+        if hasattr(self.approver, "approve_plan"):
+            return self.approver.approve_plan(calls, specs)
+        for call, spec in zip(calls, specs, strict=True):
+            if self._needs_approval(spec) and not self.approver.approve(call, spec):
+                return False
+        return True

agentkernel/approval/__init__.py

@@ -0,0 +1,23 @@
+"""Approval gate and execution boundary (design §10)."""
+
+from agentkernel.approval.base import Approver, Sandbox
+from agentkernel.approval.cli import AutoApprover, CliApprover
+from agentkernel.approval.policy import decide
+from agentkernel.approval.sandbox import (
+    DockerSandbox,
+    LocalSandbox,
+    SandboxError,
+    make_sandbox,
+)
+
+__all__ = [
+    "Approver",
+    "Sandbox",
+    "AutoApprover",
+    "CliApprover",
+    "LocalSandbox",
+    "DockerSandbox",
+    "SandboxError",
+    "make_sandbox",
+    "decide",
+]

agentkernel/approval/base.py

@@ -0,0 +1,34 @@
+"""Approver protocol (design §10.1).
+
+The loop consults the approver before executing any gated tool (one whose
+``requires_approval``, ``mutates``, or ``runs_code`` flag is set). A denial
+produces a ``ToolResult(is_error=True)``; it never raises. The Sandbox protocol
+and approval policies land in M3.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+from agentkernel.types import ToolCall
+
+if TYPE_CHECKING:
+    from agentkernel.tools import ToolSpec
+
+
+class Approver(Protocol):
+    def approve(self, call: ToolCall, spec: ToolSpec) -> bool: ...
+
+
+class Sandbox(Protocol):
+    """Execution boundary for ``runs_code`` tools (design §10.3).
+
+    ``run`` executes a command confined to ``cwd`` and returns
+    ``(exit_code, stdout, stderr)``. ``LocalSandbox`` confines to a subprocess;
+    ``DockerSandbox`` runs in a per-project container. ``close`` releases any
+    persistent resources (e.g. the container) and is a no-op for ``LocalSandbox``.
+    """
+
+    def run(self, command: str, *, cwd: str, timeout: int) -> tuple[int, str, str]: ...
+
+    def close(self) -> None: ...

agentkernel/approval/cli.py

@@ -0,0 +1,129 @@
+"""Approver implementations (design §10.2).
+
+Both apply the shared policy in ``policy.py``. ``CliApprover`` prompts the
+terminal when the policy says ``ask``; ``AutoApprover`` never prompts (for tests
+and non-interactive runs) and resolves ``ask`` to a fixed default.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from agentkernel.approval.policy import decide
+from agentkernel.types import ToolCall
+
+if TYPE_CHECKING:
+    from agentkernel.approval.risk import RiskJudge
+    from agentkernel.tools import ToolSpec
+
+
+def _summarize(call: ToolCall) -> str:
+    """One-line, side-effect-free description of a pending call for the prompt."""
+    try:
+        args = json.dumps(call.arguments, ensure_ascii=False)
+    except (TypeError, ValueError):
+        args = str(call.arguments)
+    return f"{call.name}({args})"
+
+
+class AutoApprover:
+    """Non-interactive approver. Applies policy; resolves ``ask`` to ``ask_default``.
+
+    Defaults (no args) allow everything, which is what the offline test agents
+    rely on. Pass ``ask_default=False`` to exercise the denial path.
+    """
+
+    def __init__(
+        self,
+        policy: str = "always_ask",
+        *,
+        allowlist: list[str] | None = None,
+        ask_default: bool = True,
+        risk_judge: RiskJudge | None = None,
+    ) -> None:
+        self._policy = policy
+        self._allowlist = allowlist or []
+        self._ask_default = ask_default
+        self._risk_judge = risk_judge
+
+    def approve(self, call: ToolCall, spec: ToolSpec) -> bool:
+        decision = decide(self._policy, spec, call, self._allowlist)
+        if decision == "allow":
+            return True
+        if decision == "deny":
+            return False
+        if (
+            self._policy == "smart"
+            and self._risk_judge is not None
+            and self._risk_judge.is_low_risk(call, spec) is True
+        ):
+            return True
+        return self._ask_default
+
+    def approve_plan(self, calls: list[ToolCall], specs: list[ToolSpec | None]) -> bool:
+        decisions = [
+            decide(self._policy, spec, call, self._allowlist)
+            for call, spec in zip(calls, specs, strict=True)
+        ]
+        if any(d == "deny" for d in decisions):
+            return False
+        if all(d == "allow" for d in decisions):
+            return True
+        return self._ask_default
+
+
+class CliApprover:
+    """Interactive approver: prints the pending call and reads y/n when the
+    policy requires asking. ``input_fn``/``output_fn`` are injectable for tests."""
+
+    def __init__(
+        self,
+        policy: str = "always_ask",
+        *,
+        allowlist: list[str] | None = None,
+        input_fn: Callable[[str], str] = input,
+        output_fn: Callable[[str], None] = print,
+        risk_judge: RiskJudge | None = None,
+    ) -> None:
+        self._policy = policy
+        self._allowlist = allowlist or []
+        self._input = input_fn
+        self._output = output_fn
+        self._risk_judge = risk_judge
+
+    def approve(self, call: ToolCall, spec: ToolSpec) -> bool:
+        decision = decide(self._policy, spec, call, self._allowlist)
+        if decision == "allow":
+            return True
+        if decision == "deny":
+            self._output(f"Denied by policy: {_summarize(call)}")
+            return False
+        # smart mode: let the risk judge auto-approve clearly low-risk calls;
+        # high-risk or undecided falls through to the human prompt.
+        if (
+            self._policy == "smart"
+            and self._risk_judge is not None
+            and self._risk_judge.is_low_risk(call, spec) is True
+        ):
+            self._output(f"Auto-approved (low risk): {_summarize(call)}")
+            return True
+        answer = self._input(f"Approve {_summarize(call)}? [y/N] ").strip().lower()
+        return answer in ("y", "yes")
+
+    def approve_plan(self, calls: list[ToolCall], specs: list[ToolSpec | None]) -> bool:
+        decisions = [
+            decide(self._policy, spec, call, self._allowlist)
+            for call, spec in zip(calls, specs, strict=True)
+        ]
+        if any(d == "deny" for d in decisions):
+            self._output("Denied by policy for at least one planned tool.")
+            return False
+        if all(d == "allow" for d in decisions):
+            return True
+        self._output("Proposed plan:")
+        for i, call in enumerate(calls, 1):
+            self._output(f"  {i}. {_summarize(call)}")
+        answer = self._input("Approve entire plan? [y/N] ").strip().lower()
+        return answer in ("y", "yes")

agentkernel/approval/policy.py

@@ -0,0 +1,58 @@
+"""Approval-policy decision, shared by every Approver (design §10.2).
+
+Policies: ``always_ask`` (default), ``auto_allow``, ``deny_mutations``, and
+``smart``. An optional allowlist of patterns (matched against the tool name and,
+for shell tools, the command) skips the gate. The loop only consults an approver
+for gated tools, but ``decide`` stays safe for non-gated ones too.
+
+``smart`` resolves here to ``ask`` (the safe default); the approver, which has a
+provider, may consult a risk judge before that prompt and auto-approve low-risk
+calls. ``decide`` is pure and has no model, so the judging lives in the approver.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from typing import TYPE_CHECKING, Literal
+
+from agentkernel.types import ToolCall
+
+if TYPE_CHECKING:
+    from agentkernel.tools import ToolSpec
+
+Decision = Literal["allow", "deny", "ask"]
+
+
+def _allowlisted(call: ToolCall, allowlist: list[str]) -> bool:
+    if not allowlist:
+        return False
+    targets = [call.name]
+    command = call.arguments.get("command")
+    if isinstance(command, str):
+        targets.append(command)
+    for pattern in allowlist:
+        for target in targets:
+            if target == pattern or target.startswith(pattern) or fnmatch.fnmatch(
+                target, pattern
+            ):
+                return True
+    return False
+
+
+def decide(
+    policy: str,
+    spec: ToolSpec,
+    call: ToolCall,
+    allowlist: list[str] | None = None,
+) -> Decision:
+    """Resolve a policy to allow / deny / ask for this call."""
+    if not spec.gated:
+        return "allow"
+    if _allowlisted(call, allowlist or []):
+        return "allow"
+    if policy == "auto_allow":
+        return "allow"
+    if policy == "deny_mutations":
+        return "deny" if (spec.mutates or spec.runs_code) else "allow"
+    # always_ask (default and unknown-policy fallback)
+    return "ask"

agentkernel/approval/risk.py

@@ -0,0 +1,91 @@
+"""Risk judge for the ``smart`` approval mode (design §18.1).
+
+A small auxiliary model classifies a pending gated tool call as low- or high-risk
+so the approver can auto-approve the boring ones (reading a file, listing a dir)
+and prompt only on the dangerous ones (``rm -rf``, overwriting config, anything
+irreversible). It is intentionally conservative: any parse failure or provider
+error returns ``None`` so the approver falls back to asking — a judge that can't
+decide must never silently approve.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import TYPE_CHECKING
+
+from agentkernel.types import Message
+
+if TYPE_CHECKING:
+    from agentkernel.providers import Provider
+    from agentkernel.tools import ToolSpec
+    from agentkernel.types import ToolCall
+
+_SYSTEM = (
+    "You are a security gate for an autonomous coding agent. Decide whether a "
+    "pending tool call is safe to auto-approve without a human. Treat as HIGH "
+    "risk anything destructive or irreversible: deleting or overwriting data, "
+    "force-resetting version control, modifying system or global config, "
+    "installing software, sending data over the network, or running shell "
+    "commands with broad/ambiguous scope. Treat as LOW risk read-only or easily "
+    "reversible, narrowly-scoped actions. When unsure, choose high. Respond with "
+    'ONLY a JSON object: {"risk": "low" | "high", "reason": "<short>"}.'
+)
+
+
+def _build_prompt(call: ToolCall, spec: ToolSpec | None) -> str:
+    flags = []
+    if spec is not None:
+        if spec.mutates:
+            flags.append("mutates")
+        if spec.runs_code:
+            flags.append("runs_code")
+    try:
+        args = json.dumps(call.arguments, ensure_ascii=False)
+    except (TypeError, ValueError):
+        args = str(call.arguments)
+    return (
+        f"Tool: {call.name}\n"
+        f"Flags: {', '.join(flags) or 'none'}\n"
+        f"Arguments: {args}\n\n"
+        "Classify the risk of running this call."
+    )
+
+
+def _parse_risk(text: str) -> bool | None:
+    """Return True (low risk), False (high risk), or None (undecided)."""
+    match = re.search(r"\{.*\}", text, re.DOTALL)
+    if not match:
+        return None
+    try:
+        data = json.loads(match.group(0))
+    except json.JSONDecodeError:
+        return None
+    risk = str(data.get("risk", "")).strip().lower()
+    if risk == "low":
+        return True
+    if risk == "high":
+        return False
+    return None
+
+
+class RiskJudge:
+    """Classifies a pending tool call's risk with a cheap auxiliary model."""
+
+    def __init__(self, provider: Provider, *, max_tokens: int = 256) -> None:
+        self._provider = provider
+        self._max_tokens = max_tokens
+
+    def is_low_risk(self, call: ToolCall, spec: ToolSpec | None) -> bool | None:
+        """True if safe to auto-approve, False if it should be asked, None if the
+        judge could not decide (provider error or unparseable reply)."""
+        try:
+            resp = self._provider.complete(
+                [Message(role="user", content=_build_prompt(call, spec))],
+                [],
+                max_tokens=self._max_tokens,
+                system=_SYSTEM,
+            )
+        except Exception:  # noqa: BLE001 - a judge failure must fall back to asking
+            return None
+        return _parse_risk(resp.message.content)