agent-augury 0.3.0__py3-none-any.whl

agent_augury/__init__.py

@@ -0,0 +1,3 @@
+"""agent-augury — model-agnostic passive awareness multi-agent runtime."""
+
+__version__ = "0.2"

agent_augury/agent/__init__.py

@@ -0,0 +1 @@
+"""Agent package: loop, tools, system prompt."""

agent_augury/agent/loop.py

@@ -0,0 +1,241 @@
+"""Agent loop: step() with inbox drain as single consumer (§3.5.2, §3.6).
+
+Also resolves ``$thread:N`` placeholders against this agent's own
+create_thread results, so scripted/real tool sequences can reference
+threads created earlier in the same run.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from ..backend.base import Completion, ModelBackend
+from ..server import MessageServer
+from .system_prompt import render_system_prompt
+from .tools import ToolBox
+
+Message = dict[str, Any]
+
+_THREAD_REF = re.compile(r"^\$thread:(\d+)$")
+_THREAD_BY_NAME = re.compile(r"^\$thread_by_name:(.+)$")
+
+
+@dataclass
+class StepResult:
+    """Outcome of one agent step."""
+
+    text: str | None = None
+    tool_calls: list[Any] = field(default_factory=list)
+    drained_count: int = 0
+    usage: dict[str, Any] | None = None
+
+
+def format_radio_block(messages: list[Message]) -> str:
+    """§3.6 — drained messages merge into ONE user turn wrapped in [radio].
+
+    Message content passes through unchanged; prefixes like URGENT:/FYI:
+    travel inside the content itself.
+    """
+    lines = ["[radio]"]
+    lines.extend(f"from {m['author']}: {m['content']}".rstrip() for m in messages)
+    return "\n".join(lines)
+
+
+@dataclass(frozen=True)
+class LocalTool:
+    """A non-server tool bound directly to the agent (e.g. search)."""
+
+    name: str
+    description: str
+    schema: dict[str, Any]
+    handler: Callable[[dict[str, Any]], Any]  # sync or async → JSON-serializable
+
+
+class AgentLoop:
+    """One agent's turn loop. The ONLY inbox consumer is step()."""
+
+    def __init__(
+        self,
+        agent_id: str,
+        server: MessageServer,
+        backend: ModelBackend,
+        system_prompt: str | None = None,
+        local_tools: list[LocalTool] | None = None,
+        on_tool_call: Callable[[str, str, dict[str, Any], Any], None] | None = None,
+        allowed_roots: list[str] | None = None,
+    ) -> None:
+        self.agent_id = agent_id
+        self.server = server
+        self.backend = backend
+        self.tools = ToolBox(server, allowed_roots=allowed_roots)
+        self.local_tools: dict[str, LocalTool] = {t.name: t for t in local_tools or []}
+        self.conversation: list[Message] = [
+            {
+                "role": "system",
+                "content": system_prompt or render_system_prompt(agent_id),
+            }
+        ]
+        self._custom_system_prompt = system_prompt is not None
+        # thread ids this agent created, in creation order ($thread:N source)
+        self.created_threads: list[str] = []
+        # gate-aware execution state (injected by Session each step)
+        self.gate_open: bool = True
+        self.gate_thread_id: str | None = None
+        # v0.2: current protocol phase (injected by Session each step)
+        self.current_phase: str = ""
+        # Real-time tool event callback (fires immediately on each tool execution)
+        self.on_tool_call = on_tool_call
+
+    # -- tool spec passthrough (mode-aware) ---------------------------------
+
+    @property
+    def tool_specs(self) -> list[dict[str, Any]]:
+        specs = self.tools.specs()
+        for tool in self.local_tools.values():
+            specs.append(
+                {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "schema": tool.schema,
+                }
+            )
+        return specs
+
+    def _update_phase_in_prompt(self) -> None:
+        """Update the system prompt to reflect the current phase."""
+        if self._custom_system_prompt:
+            return  # user-supplied prompt — don't overwrite
+        if self.conversation and self.conversation[0]["role"] == "system":
+            self.conversation[0]["content"] = render_system_prompt(
+                self.agent_id, self.current_phase
+            )
+
+    async def step(self) -> StepResult:
+        """One model turn. Drains the inbox first; injects a [radio] user turn."""
+        # Update system prompt with current phase
+        self._update_phase_in_prompt()
+        drained = await self.server.drain_inbox(self.agent_id)
+
+        if drained:
+            self.conversation.append(
+                {"role": "user", "content": format_radio_block(drained)}
+            )
+
+        completion: Completion = await self.backend.complete(
+            self.conversation, self.tool_specs
+        )
+        assistant_msg: Message = {"role": "assistant", "content": completion.text or ""}
+        if completion.tool_calls:
+            assistant_msg["tool_calls"] = [
+                {
+                    "id": call.id,
+                    "type": "function",
+                    "function": {
+                        "name": call.name,
+                        "arguments": json.dumps(call.arguments, ensure_ascii=False),
+                    },
+                }
+                for call in completion.tool_calls
+            ]
+        self.conversation.append(assistant_msg)
+
+        tool_results: list[Message] = []
+        for call in completion.tool_calls:
+            args = self._resolve_refs(call.arguments)
+            try:
+                result = await self._execute_tool(call.name, args)
+                if call.name == "create_thread":
+                    self.created_threads.append(json.loads(result)["thread_id"])
+            except Exception as exc:  # noqa: BLE001 — surfaced to the model verbatim
+                result = json.dumps({"error": repr(exc)}, ensure_ascii=False)
+            # Fire real-time tool event callback immediately
+            if self.on_tool_call is not None:
+                self.on_tool_call(self.agent_id, call.name, call.arguments, result)
+            tool_results.append({
+                "role": "tool",
+                "tool_call_id": call.id,
+                "content": result,
+            })
+        if tool_results:
+            self.conversation.extend(tool_results)
+
+        return StepResult(
+            text=completion.text,
+            tool_calls=completion.tool_calls,
+            drained_count=len(drained),
+            usage=completion.usage,
+        )
+
+    async def _execute_tool(self, name: str, args: dict[str, Any]) -> str:
+        if name in self.local_tools:
+            tool = self.local_tools[name]
+            value = tool.handler(args)
+            if hasattr(value, "__await__"):
+                value = await value
+            return json.dumps(value, ensure_ascii=False, default=str)
+        # gate-aware execution: block work-share on non-gate threads while gate is closed
+        if name == "send_message" and not self.gate_open:
+            thread_id = args.get("thread")
+            if thread_id:
+                # If gate_thread_id is set, block any non-gate thread
+                if self.gate_thread_id is not None and thread_id != self.gate_thread_id:
+                    return json.dumps(
+                        {
+                            "error": "gate_closed",
+                            "message": (
+                                f"Gate is CLOSED. Work-share on thread '{thread_id}' is blocked. "
+                                f"Post APPROVE on the gate thread '{self.gate_thread_id}' to open the gate."
+                            ),
+                        },
+                        ensure_ascii=False,
+                    )
+                # If gate_thread_id is None (initial state, no gate bound yet),
+                # only READY messages are allowed (to finish P1).
+                # PROPOSE/APPROVE/REJECT are NOT allowed until a gate thread
+                # is explicitly bound.
+                if self.gate_thread_id is None:
+                    content = args.get("content", "")
+                    if content != "READY:":
+                        return json.dumps(
+                            {
+                                "error": "gate_closed",
+                                "message": (
+                                    f"Gate is CLOSED. Work-share on thread '{thread_id}' is blocked. "
+                                    f"Send READY: to finish P1 exploration first."
+                                ),
+                            },
+                            ensure_ascii=False,
+                        )
+        return await self.tools.execute(self.agent_id, name, args)
+
+    def _resolve_refs(self, args: dict[str, Any]) -> dict[str, Any]:
+        resolved: dict[str, Any] = {}
+        for key, value in args.items():
+            if isinstance(value, str):
+                m = _THREAD_BY_NAME.match(value)
+                if m:
+                    resolved[key] = self._find_thread_by_name(m.group(1))
+                    continue
+                m = _THREAD_REF.match(value)
+                if m:
+                    idx = int(m.group(1))
+                    try:
+                        resolved[key] = self.created_threads[idx]
+                        continue
+                    except IndexError:
+                        raise ValueError(
+                            f"$thread:{idx} has no matching create_thread result "
+                            f"(agent {self.agent_id} created {len(self.created_threads)})"
+                        ) from None
+            resolved[key] = value
+        return resolved
+
+    def _find_thread_by_name(self, name: str) -> str:
+        """Resolve a thread id from the SSOT by name (what read_resource offers)."""
+        for thread in self.server.snapshot()["threads"]:
+            if thread["name"] == name:
+                return thread["thread_id"]
+        raise ValueError(f"no thread named {name!r} exists yet")

agent_augury/agent/system_prompt.py

@@ -0,0 +1,86 @@
+"""Model-agnostic communication-rules prompt template (§3.5.1, §2.4).
+
+v0.2: includes phase-aware instructions for P1~P5 collaboration protocol.
+"""
+
+SYSTEM_PROMPT_TEMPLATE = """\
+You are `{agent_id}`, one agent in a multi-agent team sharing radio threads.
+
+Communication rules:
+- You may open threads (`create_thread`) and post messages (`send_message`).
+- `send_message` is fire-and-forget. It returns immediately — never wait after sending.
+- To address teammates use mentions: `"mentions": ["agent-2"]` in send_message.
+  In message text, write mentions as @agent-2 (surface syntax).
+- An EMPTY mentions list is a broadcast to everyone in the thread except you.
+- Prefix your messages when useful:
+  - "FYI: ..." or "(FYI) ..." — reference only, no reply expected.
+  - "URGENT: ..." or "(URGENT) ..." — affects what the receiver is doing right
+    now; they must handle it before continuing their current approach.
+- Incoming teammate messages appear automatically as a single [radio] block in
+  a user turn. Read it at your next step boundary and keep working.
+- `read_resource` dumps full thread/message state. Use it only when you need
+  history or recovery — it is never pushed to you automatically.
+
+Filesystem tools (for exploring code and files):
+- `read_file(path)` — read a file's content. Use this to examine source code,
+  configuration files, or any text file you need to understand.
+- `list_directory(path)` — list files and directories. Use this to explore
+  project structure before reading specific files.
+- `write_file(path, content)` — write content to a file. Use this to create
+  reports, notes, or modified files.
+
+When investigating a codebase, start with `list_directory` to understand the
+structure, then use `read_file` on relevant files. Always read files before
+making claims about their contents.
+
+{phase_instructions}
+"""
+
+# Phase-specific instruction templates
+_PHASE_INSTRUCTIONS = {
+    "P1_EXPLORE": """\
+Current phase: **P1 EXPLORE**
+- Independently explore the task and gather information.
+- Formulate sub-questions and draft initial findings.
+- Do NOT send messages to teammates yet — exploration is silent.
+- When you are done exploring, send ``READY:`` to signal completion.
+  Only ``READY:`` is recognized; ``READYFOO`` or similar is ignored.
+  P1 finishes automatically once ALL participants have sent ``READY:``.
+  Note: READY: is the ONLY message allowed during P1 — all other
+  send_message calls will be blocked by the gate.""",
+    "P2_SPLIT": """\
+Current phase: **P2 SPLIT**
+- Pool your discoveries with teammates on the plan thread.
+- Negotiate a split of sub-questions among agents.
+- Propose a division with `PROPOSE:` and approve with `APPROVE:`.
+- The phase advances only when ALL agents approve.""",
+    "P3_EXECUTE": """\
+Current phase: **P3 EXECUTE**
+- Execute your assigned share of the work.
+- Post work logs and intermediate findings to the work thread immediately.
+- Share contradictions, obstacles, or abandoned approaches.""",
+    "P4_REVIEW": """\
+Current phase: **P4 REVIEW**
+- Broadcast your results with supporting evidence on the results thread.
+- Review teammates' submissions for factual conflicts, insufficient evidence,
+  or omissions. Flag issues explicitly.""",
+    "P5_SUBMIT": """\
+Current phase: **P5 SUBMIT**
+- The assembler composes the final answer from approved results.
+- Broadcast the final answer for review.
+- Approve with `APPROVE:` to submit, or request changes with `REJECT:`.""",
+}
+
+
+def render_system_prompt(agent_id: str, phase: str = "") -> str:
+    """Render the system prompt for an agent.
+
+    Args:
+        agent_id: The agent's identifier.
+        phase: Current protocol phase (e.g. "P2_SPLIT"). If empty, no phase
+            instructions are included.
+    """
+    phase_instructions = _PHASE_INSTRUCTIONS.get(phase, "")
+    return SYSTEM_PROMPT_TEMPLATE.format(
+        agent_id=agent_id, phase_instructions=phase_instructions
+    )

agent_augury/agent/tools.py

@@ -0,0 +1,203 @@
+"""Agent-facing tools backed by the internal message server (§3.5.1).
+
+Exposes: create_thread, send_message, read_resource, read_file,
+list_directory, write_file.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..server import MessageServer
+
+
+def _json(result: Any) -> str:
+    return json.dumps(result, ensure_ascii=False)
+
+
+class ToolBox:
+    """Binds server operations into model-callable tools."""
+
+    def __init__(self, server: MessageServer, allowed_roots: list[str] | None = None) -> None:
+        self.server = server
+        self.allowed_roots = allowed_roots
+
+    # -- tool specs ----------------------------------------------------------
+
+    def specs(self) -> list[dict[str, Any]]:
+        """JSON-schema tool specs."""
+        return [
+            {
+                "name": "create_thread",
+                "description": "Open a named conversation thread with the given participants and return its id.",
+                "schema": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string"},
+                        "participants": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                        },
+                    },
+                    "required": ["name", "participants"],
+                },
+            },
+            {
+                "name": "send_message",
+                "description": (
+                    "Post a message to a thread. Fire-and-forget: returns immediately. "
+                    "Empty mentions broadcasts to the thread's participants (except you). "
+                    'Prefix content with "(FYI)" or "(URGENT)" when appropriate.'
+                ),
+                "schema": {
+                    "type": "object",
+                    "properties": {
+                        "thread": {"type": "string", "description": "thread id"},
+                        "content": {"type": "string"},
+                        "mentions": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "agent ids to address; empty = broadcast",
+                        },
+                    },
+                    "required": ["thread", "content"],
+                },
+            },
+            {
+                "name": "read_resource",
+                "description": "Explicit full state dump of threads/messages for recovery or aggregation. Never injected automatically.",
+                "schema": {"type": "object", "properties": {}},
+            },
+            {
+                "name": "read_file",
+                "description": "Read a file's content from the filesystem. Returns the file content as text.",
+                "schema": {
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string", "description": "file path to read"},
+                    },
+                    "required": ["path"],
+                },
+            },
+            {
+                "name": "list_directory",
+                "description": "List contents of a directory. Returns entries with name, is_dir, and size.",
+                "schema": {
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string", "description": "directory path to list", "default": "."},
+                    },
+                },
+            },
+            {
+                "name": "write_file",
+                "description": "Write content to a file on the filesystem. Creates parent directories as needed.",
+                "schema": {
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string", "description": "file path to write"},
+                        "content": {"type": "string", "description": "content to write"},
+                    },
+                    "required": ["path", "content"],
+                },
+            },
+        ]
+
+    # -- execution -----------------------------------------------------------
+
+    async def execute(self, agent_id: str, name: str, args: dict[str, Any]) -> str:
+        if name == "create_thread":
+            tid = await self.server.create_thread(
+                args["name"], participants=list(args["participants"])
+            )
+            return _json({"thread_id": tid})
+        if name == "send_message":
+            mid = await self.server.send_message(
+                args["thread"],
+                author=agent_id,
+                content=args["content"],
+                mentions=list(args.get("mentions") or []),
+            )
+            return _json({"message_id": mid, "status": "sent"})
+        if name == "read_resource":
+            snap = self.server.snapshot()
+            self.server._emit_event({
+                "type": "read_resource",
+                "agent_id": agent_id,
+                "threads": len(snap["threads"]),
+                "messages": len(snap["messages"]),
+                "timestamp": int(__import__("time").time()),
+            })
+            return _json(snap)
+        if name == "read_file":
+            return await self._read_file(args)
+        if name == "list_directory":
+            return await self._list_directory(args)
+        if name == "write_file":
+            return await self._write_file(args)
+        raise ValueError(f"unknown tool: {name}")
+
+    # -- filesystem tools -----------------------------------------------------
+
+    async def _read_file(self, args: dict[str, Any]) -> str:
+        """Read a file's content."""
+        import os
+        path = args.get("path", "")
+        if not path:
+            return _json({"error": "path is required"})
+        # Security: resolve to absolute path and check it's within allowed roots
+        abs_path = os.path.abspath(path)
+        allowed_roots = self.allowed_roots
+        if allowed_roots:
+            if not any(abs_path.startswith(os.path.abspath(root)) for root in allowed_roots):
+                return _json({"error": f"path outside allowed roots: {path}"})
+        try:
+            with open(abs_path, "r", encoding="utf-8", errors="replace") as f:
+                content = f.read()
+            return _json({"path": abs_path, "content": content, "size": len(content)})
+        except Exception as exc:
+            return _json({"error": f"failed to read {path}: {exc}"})
+
+    async def _list_directory(self, args: dict[str, Any]) -> str:
+        """List directory contents."""
+        import os
+        path = args.get("path", ".")
+        abs_path = os.path.abspath(path)
+        allowed_roots = self.allowed_roots
+        if allowed_roots:
+            if not any(abs_path.startswith(os.path.abspath(root)) for root in allowed_roots):
+                return _json({"error": f"path outside allowed roots: {path}"})
+        try:
+            entries = []
+            for entry in os.listdir(abs_path):
+                full = os.path.join(abs_path, entry)
+                stat = os.stat(full)
+                entries.append({
+                    "name": entry,
+                    "is_dir": os.path.isdir(full),
+                    "size": stat.st_size,
+                })
+            return _json({"path": abs_path, "entries": entries})
+        except Exception as exc:
+            return _json({"error": f"failed to list {path}: {exc}"})
+
+    async def _write_file(self, args: dict[str, Any]) -> str:
+        """Write content to a file."""
+        import os
+        path = args.get("path", "")
+        content = args.get("content", "")
+        if not path:
+            return _json({"error": "path is required"})
+        abs_path = os.path.abspath(path)
+        allowed_roots = self.allowed_roots
+        if allowed_roots:
+            if not any(abs_path.startswith(os.path.abspath(root)) for root in allowed_roots):
+                return _json({"error": f"path outside allowed roots: {path}"})
+        try:
+            os.makedirs(os.path.dirname(abs_path), exist_ok=True)
+            with open(abs_path, "w", encoding="utf-8") as f:
+                f.write(content)
+            return _json({"path": abs_path, "size": len(content), "status": "written"})
+        except Exception as exc:
+            return _json({"error": f"failed to write {path}: {exc}"})

agent_augury/auth/__init__.py

@@ -0,0 +1,6 @@
+"""OAuth authentication for agent-augury.
+
+Provides browser-based OAuth flows (device code, PKCE) and token persistence.
+Reuses Hermes Agent's proven OAuth patterns while staying independent.
+"""
+