agent86 1.0.0__py3-none-any.whl

agent86/__init__.py

@@ -0,0 +1,14 @@
+"""agent86 — an agentic harness on the command line.
+
+A Python CLI that connects to remote or local models and lets them use tools and
+skills, built as a faithful implementation of the five-tier architecture and four
+pillars from *The Agentic Harness* (Tony Fleming, 2026).
+
+Core principle — Separation of Concerns: the Cognitive Core (the model) only ever
+*proposes* the next step. The deterministic harness validates, executes, and persists.
+The model never touches the sandbox, the database, or the terminal directly.
+"""
+
+__version__ = "1.0.0"
+
+__all__ = ["__version__"]

agent86/__main__.py

@@ -0,0 +1,6 @@
+"""Enable `python -m agent86`."""
+
+from agent86.cli import app
+
+if __name__ == "__main__":
+    app()

agent86/agents/__init__.py

@@ -0,0 +1,17 @@
+"""Multi-agent (MAS) — collaboration & negotiation.
+
+An ``Agent`` is a harness instance bound to a role, system prompt, and toolset.
+Agents communicate via structured message *envelopes* (never raw natural language as a
+wire protocol — the book's "Babel problem") over an in-process async broker. The
+orchestrator spawns sub-agents, wires topologies (supervisor / pipeline / blackboard),
+and applies harness-level conflict resolution rather than trusting pure LLM debate.
+
+v0.1 ships single-agent-first with this scaffolding present; supervisor topology is the
+first wired path (Phase 8).
+
+Modules:
+    agent.py         — Agent runtime wrapper
+    envelope.py      — structured agent message envelope
+    broker.py        — in-process async message broker
+    orchestrator.py  — sub-agent spawning, topologies, conflict resolution
+"""

agent86/agents/broker.py

@@ -0,0 +1,45 @@
+"""In-process message broker (the harness as communication broker).
+
+A simple synchronous pub/sub bus: agents post :class:`AgentMessage` envelopes addressed to a
+recipient, and a recipient drains its inbox. This is the local-topology substrate the
+supervisor orchestrator runs on; a networked broker (Redis/NATS) would slot in behind the
+same interface for distributed MAS (a Phase-9+ concern).
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict, deque
+
+from agent86.agents.envelope import AgentMessage
+
+
+class MessageBus:
+    def __init__(self) -> None:
+        self._inboxes: dict[str, deque[AgentMessage]] = defaultdict(deque)
+        self._log: list[AgentMessage] = []
+
+    def send(self, message: AgentMessage) -> None:
+        self._inboxes[message.recipient].append(message)
+        self._log.append(message)
+
+    def receive(self, recipient: str) -> AgentMessage | None:
+        inbox = self._inboxes.get(recipient)
+        return inbox.popleft() if inbox else None
+
+    def drain(self, recipient: str) -> list[AgentMessage]:
+        inbox = self._inboxes.get(recipient)
+        if not inbox:
+            return []
+        out = list(inbox)
+        inbox.clear()
+        return out
+
+    def pending(self, recipient: str) -> int:
+        return len(self._inboxes.get(recipient, ()))
+
+    @property
+    def history(self) -> list[AgentMessage]:
+        return list(self._log)
+
+
+__all__ = ["MessageBus"]

agent86/agents/envelope.py

@@ -0,0 +1,43 @@
+"""The agent message envelope.
+
+The book's answer to the "Babel problem": agents never exchange raw natural language as a
+wire protocol. Every inter-agent message is a structured envelope with an explicit sender,
+recipient, intent, and correlation id, so the harness can route, match, and audit it.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class Intent(StrEnum):
+    REQUEST = "request"  # please perform this task
+    RESPONSE = "response"  # here is the result
+    INFORM = "inform"  # fyi, no reply expected
+    ERROR = "error"  # the task failed
+
+
+@dataclass
+class AgentMessage:
+    sender: str
+    recipient: str
+    intent: Intent
+    content: str
+    correlation_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    metadata: dict = field(default_factory=dict)
+    id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+
+    def reply(self, content: str, intent: Intent = Intent.RESPONSE) -> AgentMessage:
+        """Build a correlated reply from recipient back to sender."""
+        return AgentMessage(
+            sender=self.recipient,
+            recipient=self.sender,
+            intent=intent,
+            content=content,
+            correlation_id=self.correlation_id,
+        )
+
+
+__all__ = ["AgentMessage", "Intent"]

agent86/agents/orchestrator.py

@@ -0,0 +1,48 @@
+"""Supervisor orchestrator (multi-agent topology).
+
+The programmatic counterpart to the model-driven ``delegate`` tool: fan a set of role-scoped
+tasks out to sub-agents and collect their results as correlated :class:`AgentMessage`
+envelopes on the bus. Sub-agents run sequentially in-process (the sync harness); the envelope
+protocol keeps the topology explicit and auditable.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from agent86.agents.broker import MessageBus
+from agent86.agents.envelope import AgentMessage, Intent
+from agent86.agents.subagent import SubAgent
+
+if TYPE_CHECKING:
+    from agent86.orchestration.loop import Harness
+
+
+class SupervisorOrchestrator:
+    def __init__(self, harness: Harness, bus: MessageBus | None = None):
+        self.h = harness
+        self.bus = bus or MessageBus()
+
+    def fan_out(
+        self, tasks: list[tuple[str, str]], supervisor: str = "supervisor"
+    ) -> list[AgentMessage]:
+        """Run each (role, task) on a sub-agent; return their reply envelopes in order."""
+        replies: list[AgentMessage] = []
+        for role, task in tasks:
+            request = AgentMessage(
+                sender=supervisor, recipient=role, intent=Intent.REQUEST, content=task
+            )
+            self.bus.send(request)
+            try:
+                result, usage = SubAgent(self.h, role, depth=1).run(task)
+                reply = request.reply(result, intent=Intent.RESPONSE)
+                # What the fan-out cost, per branch, is part of the audit trail.
+                reply.metadata["usage"] = usage.model_dump()
+            except Exception as exc:  # a failing sub-agent must not sink the whole fan-out
+                reply = request.reply(f"{type(exc).__name__}: {exc}", intent=Intent.ERROR)
+            self.bus.send(reply)
+            replies.append(reply)
+        return replies
+
+
+__all__ = ["SupervisorOrchestrator"]

agent86/agents/subagent.py

@@ -0,0 +1,169 @@
+"""Sub-agent runtime (multi-agent systems).
+
+A ``SubAgent`` is a role-scoped Reason->Act->Observe loop that *reuses* the parent harness's
+provider, tool registry, sandbox, and approval gate — so a delegated task gets the same
+guardrails and observability as the main agent, without rebuilding memory/MCP/tracing. Its
+depth is tracked so delegation can't recurse without bound.
+
+Accountability is the other half of that reuse: a sub-agent runs under the parent's step and
+context budgets, reports every model call to the same recorder tagged with its role and depth,
+and hands its token usage back so the parent turn's cost includes what it spent. A delegated
+task is not a way to escape the harness's limits.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+from agent86.orchestration.circuit import CircuitBreaker, CircuitTripped
+from agent86.tools.base import ToolContext
+from agent86.types import (
+    CompletionRequest,
+    Message,
+    Role,
+    ToolCall,
+    ToolResult,
+    Usage,
+    invalid_arguments_result,
+)
+
+if TYPE_CHECKING:
+    from agent86.orchestration.loop import Harness
+
+#: Used when the config predates ``agents.max_steps``.
+DEFAULT_SUB_MAX_STEPS = 8
+
+_ROLE_PREAMBLE = (
+    "You are a '{role}' sub-agent operating inside a larger agent system. You were delegated "
+    "a focused task by a supervising agent. Use tools as needed, complete the task precisely, "
+    "and return ONLY the final result — no preamble."
+)
+
+
+class SubAgent:
+    def __init__(self, harness: Harness, role: str, depth: int):
+        self.h = harness
+        self.role = role or "assistant"
+        self.depth = depth
+        # A context whose spawn() delegates one level deeper, so nested delegation is depth-aware.
+        self.ctx: ToolContext = replace(
+            harness.context,
+            spawn=lambda r, t: harness.spawn_subagent(r, t, depth + 1),
+        )
+
+    @property
+    def max_steps(self) -> int:
+        """Step budget for this sub-agent, from ``agents.max_steps``."""
+        return getattr(self.h.config.agents, "max_steps", DEFAULT_SUB_MAX_STEPS)
+
+    def _system(self) -> Message:
+        """Role preamble + the parent's compiled system prompt.
+
+        Sub-agents used to get the persona and nothing else: no environment facts and — the
+        real problem — no skills list, so ``use_skill`` was advertised to them as a tool with
+        no way of knowing what to ask it for. ``build_system_prompt``'s output, which the
+        harness compiled once at startup, is reused verbatim beneath the preamble.
+        """
+        return Message(
+            role=Role.SYSTEM,
+            content=f"{_ROLE_PREAMBLE.format(role=self.role)}\n\n{self.h.system_prompt.content}",
+        )
+
+    def _specs(self):
+        specs = self.h.registry.specs()
+        # At max depth, hide `delegate` so this sub-agent cannot spawn further.
+        if self.depth >= self.h.config.agents.max_depth:
+            specs = [s for s in specs if s.name != "delegate"]
+        return specs
+
+    def run(self, task: str) -> tuple[str, Usage]:
+        """Run the delegated task to completion; return its answer and what it cost."""
+        provider = self.h.provider
+        sid = f"sub:{self.role}"
+        system = self._system()
+        messages: list[Message] = [Message(role=Role.USER, content=task)]
+        breaker = CircuitBreaker(self.h.config.limits, max_steps=self.max_steps)
+        spent = Usage()
+
+        while True:
+            try:
+                breaker.before_step()
+            except CircuitTripped as exc:
+                return f"[sub-agent '{self.role}' halted: {exc}]", spent
+
+            # Same context-window discipline as the main loop: a sub-agent that ran many
+            # tool calls could otherwise overflow the window and fail its last model call.
+            # The system message is held out of the trim so it can never be the part dropped.
+            convo = self.h.working.fit(messages, provider.count_tokens)
+            completion = provider.complete(
+                CompletionRequest(
+                    model=provider.model,
+                    messages=[system, *convo],
+                    tools=self._specs(),
+                    temperature=0.0,
+                )
+            )
+            breaker.record_step(completion.usage)
+            spent = spent + completion.usage
+            self.h.recorder.event(
+                sid,
+                "model_call",
+                agent=self.role,
+                depth=self.depth,
+                step=breaker.steps,
+                model=provider.model,
+                input_tokens=completion.usage.input_tokens,
+                output_tokens=completion.usage.output_tokens,
+                cost_usd=completion.usage.cost_usd,
+                stop_reason=completion.stop_reason,
+                tool_calls=[tc.name for tc in completion.tool_calls],
+            )
+            messages.append(
+                Message(
+                    role=Role.ASSISTANT,
+                    content=completion.text,
+                    tool_calls=completion.tool_calls,
+                )
+            )
+
+            if not completion.tool_calls:
+                self.h.recorder.event(
+                    sid, "subagent_done", role=self.role, depth=self.depth,
+                    steps=breaker.steps, cost_usd=spent.cost_usd,
+                )
+                return completion.text, spent
+
+            for call in completion.tool_calls:
+                result = self._run_tool(call)
+                content = self.h._observe(result, call.name, sid)
+                messages.append(
+                    Message(role=Role.TOOL, content=content, tool_call_id=call.id, name=call.name)
+                )
+                try:
+                    breaker.record_tool_result(result.ok)
+                except CircuitTripped as exc:
+                    return f"[sub-agent '{self.role}' halted: {exc}]", spent
+
+    def _run_tool(self, call: ToolCall) -> ToolResult:
+        # Same interception as the main loop: unparseable arguments never reach a tool.
+        invalid = call.invalid_arguments
+        if invalid is not None:
+            return invalid_arguments_result(call, invalid)
+        tool = self.h.registry.get(call.name)
+        if tool is None:
+            return self.h.registry.dispatch(call, self.ctx)
+        decision = self.h.gate.decide(tool, call)
+        if not decision.approved:
+            return ToolResult(
+                call_id=call.id, name=call.name, ok=False,
+                error=f"Not executed: {decision.reason}.",
+            )
+        result = self.h.registry.dispatch(call, self.ctx)
+        self.h.recorder.event(
+            f"sub:{self.role}", "tool_call", tool=call.name, ok=result.ok, depth=self.depth
+        )
+        return result
+
+
+__all__ = ["SubAgent", "DEFAULT_SUB_MAX_STEPS"]