rrft 0.1.0a0__tar.gz

rrft-0.1.0a0/.gitignore

@@ -0,0 +1,11 @@
+.venv
+venv
+__pycache__
+.claude
+.ruff_cache
+.pytest_cache
+.mypy_cache
+dist
+*.egg-info
+/docs/plans
+.hypothesis

rrft-0.1.0a0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0a0
+
+First version.

rrft-0.1.0a0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: rrft
+Version: 0.1.0a0
+Summary: rrft - file tree agent engine
+Author-email: 0x0064 <user.frndvrgs@gmail.com>
+Keywords: agent,ai,assistant,file,python,rrft,sdk,tree
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.20; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# rrft
+
+rrft - file tree agent engine
+
+## License
+
+MIT (pending).

rrft-0.1.0a0/README.md

@@ -0,0 +1,7 @@
+# rrft
+
+rrft - file tree agent engine
+
+## License
+
+MIT (pending).

rrft-0.1.0a0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "rrft"
+version = "0.1.0a0"
+description = "rrft - file tree agent engine"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    {name = "0x0064", email = "user.frndvrgs@gmail.com"},
+]
+keywords = [
+    "rrft",
+    "file",
+    "tree",
+    "assistant",
+    "agent",
+    "sdk",
+    "ai",
+    "python"
+]
+
+dependencies = [
+    "pydantic>=2.6",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "hypothesis>=6.100",
+    "ruff>=0.5",
+    "mypy>=1.20",
+]
+
+[project.scripts]
+rrft = "rrft.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rrft"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "B", "UP", "SIM"]
+ignore = ["E501"]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.20.0",
+]

rrft-0.1.0a0/src/rrft/__init__.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from rrft.agent import Agent
+from rrft.errors import BaseError, ProviderError, ScopeError
+from rrft.protocol import (
+    Message,
+    Provider,
+    ProviderReply,
+    ToolCall,
+    ToolSpec,
+)
+from rrft.tools.grep import GrepTool
+from rrft.tools.ls import LSTool
+from rrft.tools.read import ReadTool
+from rrft.tools.skill import SkillTool
+
+__version__ = "0.0.0"
+
+__all__ = [
+    "Agent",
+    "Message",
+    "ToolCall",
+    "ToolSpec",
+    "GrepTool",
+    "LSTool",
+    "Provider",
+    "ProviderError",
+    "ProviderReply",
+    "ReadTool",
+    "ScopeError",
+    "SkillTool",
+    "BaseError",
+    "__version__",
+]

rrft-0.1.0a0/src/rrft/agent.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, PrivateAttr
+
+from rrft.harness import Harness
+from rrft.scopes import build_scope
+from rrft.tools.base import Tool
+from rrft.tools.grep import GrepTool
+from rrft.tools.ls import LSTool
+from rrft.tools.read import ReadTool
+from rrft.tools.skill import SkillTool
+
+
+def _default_tools() -> list[Tool]:
+    return [ReadTool(), GrepTool(), LSTool(), SkillTool()]
+
+
+class Agent(BaseModel):
+    root: Path
+    provider: Any
+    namespaces: list[str] = Field(default_factory=list)
+    tools: list[Tool] = Field(default_factory=_default_tools)
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    _harness: Harness = PrivateAttr()
+    _locks: dict[str, asyncio.Lock] = PrivateAttr(default_factory=dict)
+    _locks_guard: asyncio.Lock = PrivateAttr(default_factory=asyncio.Lock)
+
+    def model_post_init(self, __context: object) -> None:
+        self._harness = Harness(agent_root=self.root, provider=self.provider, tools=self.tools)
+
+    async def _lock_for(self, key: str) -> asyncio.Lock:
+        async with self._locks_guard:
+            lock = self._locks.get(key)
+            if lock is None:
+                lock = asyncio.Lock()
+                self._locks[key] = lock
+            return lock
+
+    async def turn(self, session_id: str, message: str, scope: dict[str, str]) -> str:
+        parsed = build_scope(self.namespaces, scope)
+        lock = await self._lock_for(f"{parsed.leaf}::{session_id}")
+        async with lock:
+            return await self._harness.turn(scope=parsed, session_id=session_id, message=message)
+
+    async def resume(self, session_id: str, scope: dict[str, str]) -> str:
+        parsed = build_scope(self.namespaces, scope)
+        lock = await self._lock_for(f"{parsed.leaf}::{session_id}")
+        async with lock:
+            return await self._harness.resume(scope=parsed, session_id=session_id)

rrft-0.1.0a0/src/rrft/boot.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from rrft.scopes import Scope
+
+_LABELS = ["AGENT", "INDEX", "INSTRUCTIONS", "SKILLS", "KNOWLEDGE", "MEMORY", "SESSIONS"]
+
+
+def build_boot_bundle(agent_root: Path, scope: Scope) -> str:
+    scope_dir = agent_root / "data" / scope.leaf
+    sources = [
+        agent_root / "AGENT.md",
+        agent_root / "INDEX.md",
+        agent_root / "instructions" / "_index.md",
+        agent_root / "skills" / "_index.md",
+        agent_root / "knowledge" / "_index.md",
+        scope_dir / "memory" / "MEMORY.md",
+        scope_dir / "sessions" / "_index.md",
+    ]
+    sections: list[str] = []
+    for label, path in zip(_LABELS, sources, strict=True):
+        if path.exists():
+            sections.append(f"<<<{label}>>>\n{path.read_text(encoding='utf-8')}")
+    return "\n\n".join(sections)

rrft-0.1.0a0/src/rrft/cli.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+from rrft import __version__
+from rrft.boot import build_boot_bundle
+from rrft.path_jail import PathJail
+from rrft.scopes import build_scope
+from rrft.tools.base import Tool, ToolContext, ToolResult
+from rrft.tools.grep import GrepInput, GrepTool
+from rrft.tools.ls import LSInput, LSTool
+from rrft.tools.read import ReadInput, ReadTool
+from rrft.tools.skill import SkillInput, SkillTool
+
+_AGENT_TEMPLATE = """\
+---
+name: my-agent
+persona: write your agent's persona here
+---
+
+# My Agent
+
+You are a [describe what this agent does].
+
+## How you work
+
+- Read `INDEX.md` first to orient yourself in the filetree.
+- Use `Grep` to find relevant passages in `knowledge/`.
+- Use `Read` to pull the full text of a document when needed.
+- Use `Skill` when the user's request matches a named procedure in `skills/`.
+"""
+
+_INDEX_TEMPLATE = """\
+# Map
+
+- `AGENT.md` — who you are, how you work
+- `instructions/` — behavioral rules (tone, escalation, refusal policy)
+- `skills/` — triggerable procedures, one folder per skill
+- `knowledge/` — reference material, organized by topic
+"""
+
+_SUB_INDEX_TEMPLATES = {
+    "instructions": "# Instructions\n\n(empty — add behavioral docs here)\n",
+    "skills": "# Skills\n\n(empty — add skills as folders containing `SKILL.md`)\n",
+    "knowledge": "# Knowledge\n\n(empty — add reference material here)\n",
+}
+
+_REQUIRED_FILES = (
+    "AGENT.md",
+    "INDEX.md",
+    "instructions/_index.md",
+    "skills/_index.md",
+    "knowledge/_index.md",
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="rrft",
+        description="Filesystem-backed agent SDK — direct tool access for debugging and scaffolding.",
+    )
+    parser.add_argument("--version", action="version", version=f"rrft {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_init = sub.add_parser("init", help="scaffold a new agent tree")
+    p_init.add_argument("path", help="directory to create")
+
+    p_inspect = sub.add_parser("inspect", help="validate an agent tree and show its shape")
+    p_inspect.add_argument("root", help="path to an agent tree")
+
+    p_boot = sub.add_parser("boot", help="print the boot bundle for a scope")
+    p_boot.add_argument("root")
+    p_boot.add_argument(
+        "--namespace",
+        action="append",
+        default=[],
+        metavar="KEY",
+        help="declared namespace key (repeatable, order matters)",
+    )
+    p_boot.add_argument(
+        "--scope",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="scope value (repeatable)",
+    )
+
+    p_read = sub.add_parser("read", help="run the Read tool directly")
+    p_read.add_argument("root")
+    p_read.add_argument("file", help="file path inside the agent tree")
+    p_read.add_argument("--offset", type=int, default=0)
+    p_read.add_argument("--limit", type=int, default=None)
+
+    p_grep = sub.add_parser("grep", help="run the Grep tool directly (ripgrep-backed)")
+    p_grep.add_argument("root")
+    p_grep.add_argument("pattern")
+    p_grep.add_argument("--path", default=None, help="restrict to this subtree")
+    p_grep.add_argument("--glob", default=None, help="filename filter, e.g. '*.md'")
+    p_grep.add_argument("-i", "--case-insensitive", action="store_true")
+    p_grep.add_argument("--mode", choices=["files", "content"], default="files")
+    p_grep.add_argument("--limit", type=int, default=250)
+
+    p_ls = sub.add_parser("ls", help="run the LS tool directly")
+    p_ls.add_argument("root")
+    p_ls.add_argument("--path", default=None)
+    p_ls.add_argument("--limit", type=int, default=250)
+
+    p_skill = sub.add_parser("skill", help="load a skill body by name")
+    p_skill.add_argument("root")
+    p_skill.add_argument("name", help="skill folder name under skills/")
+
+    args = parser.parse_args(argv)
+    handlers = {
+        "init": _init,
+        "inspect": _inspect,
+        "boot": _boot,
+        "read": _read,
+        "grep": _grep,
+        "ls": _ls,
+        "skill": _skill,
+    }
+    return handlers[args.cmd](args)
+
+
+def _init(args: argparse.Namespace) -> int:
+    root = Path(args.path)
+    if root.exists() and any(root.iterdir()):
+        print(f"error: {root} exists and is not empty", file=sys.stderr)
+        return 2
+    root.mkdir(parents=True, exist_ok=True)
+    (root / "AGENT.md").write_text(_AGENT_TEMPLATE)
+    (root / "INDEX.md").write_text(_INDEX_TEMPLATE)
+    for name, template in _SUB_INDEX_TEMPLATES.items():
+        folder = root / name
+        folder.mkdir()
+        (folder / "_index.md").write_text(template)
+    print(f"scaffolded agent at {root.resolve()}")
+    return 0
+
+
+def _inspect(args: argparse.Namespace) -> int:
+    root = Path(args.root)
+    if not root.exists():
+        print(f"error: not found: {root}", file=sys.stderr)
+        return 2
+    missing = [rel for rel in _REQUIRED_FILES if not (root / rel).exists()]
+    if missing:
+        print(f"invalid agent tree at {root}: missing", file=sys.stderr)
+        for rel in missing:
+            print(f"  {rel}", file=sys.stderr)
+        return 1
+    print(f"valid agent tree: {root.resolve()}")
+    for entry in sorted(root.iterdir()):
+        if entry.name.startswith("."):
+            continue
+        if entry.is_dir():
+            md_count = sum(1 for _ in entry.rglob("*.md"))
+            print(f"  {entry.name}/  ({md_count} .md files)")
+        else:
+            print(f"  {entry.name}")
+    return 0
+
+
+def _boot(args: argparse.Namespace) -> int:
+    root = Path(args.root)
+    scope_values = _parse_scope(args.scope)
+    scope = build_scope(args.namespace, scope_values)
+    print(build_boot_bundle(root, scope))
+    return 0
+
+
+def _read(args: argparse.Namespace) -> int:
+    return asyncio.run(
+        _run_tool(
+            Path(args.root),
+            ReadTool(),
+            ReadInput(path=args.file, offset=args.offset, limit=args.limit),
+        )
+    )
+
+
+def _grep(args: argparse.Namespace) -> int:
+    return asyncio.run(
+        _run_tool(
+            Path(args.root),
+            GrepTool(),
+            GrepInput(
+                pattern=args.pattern,
+                path=args.path,
+                glob=args.glob,
+                case_insensitive=args.case_insensitive,
+                mode=args.mode,
+                head_limit=args.limit,
+            ),
+        )
+    )
+
+
+def _ls(args: argparse.Namespace) -> int:
+    return asyncio.run(
+        _run_tool(
+            Path(args.root),
+            LSTool(),
+            LSInput(path=args.path, limit=args.limit),
+        )
+    )
+
+
+def _skill(args: argparse.Namespace) -> int:
+    return asyncio.run(_run_tool(Path(args.root), SkillTool(), SkillInput(name=args.name)))
+
+
+async def _run_tool(root: Path, tool: Tool, input_obj) -> int:  # type: ignore[type-arg]
+    context = ToolContext(
+        path_jail=PathJail(
+            read_roots=[
+                root / "AGENT.md",
+                root / "INDEX.md",
+                root / "instructions",
+                root / "skills",
+                root / "knowledge",
+            ],
+            write_roots=[],
+        ),
+        agent_root=root.resolve(),
+        cancel=asyncio.Event(),
+    )
+    result: ToolResult = await tool.call(input_obj, context)
+    return _emit(result)
+
+
+def _emit(result: ToolResult) -> int:
+    if result.is_error:
+        print(result.content, file=sys.stderr)
+        return 1
+    print(result.content)
+    return 0
+
+
+def _parse_scope(items: list[str]) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for item in items:
+        if "=" not in item:
+            print(
+                f"error: invalid --scope '{item}' (expected KEY=VALUE)",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+        key, value = item.split("=", 1)
+        out[key] = value
+    return out
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rrft-0.1.0a0/src/rrft/errors.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+
+class BaseError(Exception):
+    pass
+
+
+class ScopeError(BaseError):
+    pass
+
+
+class ProviderError(BaseError):
+    pass

rrft-0.1.0a0/src/rrft/event_log.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections import deque
+from datetime import datetime
+from pathlib import Path as _Path
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Discriminator, Field, PrivateAttr, TypeAdapter, ValidationError
+
+from rrft.errors import BaseError
+
+
+class _EventBase(BaseModel):
+    at: datetime
+    turn: int
+
+    model_config = {"frozen": True}
+
+
+class MessageEvent(_EventBase):
+    type: Literal["message"] = "message"
+    role: Literal["user", "assistant", "system"]
+    content: str
+    user_id: str | None = None
+    usage: dict[str, int] | None = None
+
+
+class ToolCallEvent(_EventBase):
+    type: Literal["tool_call"] = "tool_call"
+    role: Literal["assistant"] = "assistant"
+    id: str
+    tool: str
+    args: dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolResultEvent(_EventBase):
+    type: Literal["tool_result"] = "tool_result"
+    role: Literal["tool"] = "tool"
+    id: str
+    is_error: bool
+    content: str
+
+
+Event = Annotated[
+    MessageEvent | ToolCallEvent | ToolResultEvent,
+    Discriminator("type"),
+]
+
+_ADAPTER: TypeAdapter[Event] = TypeAdapter(Event)
+
+
+def dump_event(event: Event) -> str:
+    return (
+        _ADAPTER.dump_json(event, warnings="error")
+        .decode("utf-8")
+        .replace("\u2028", "\\u2028")
+        .replace("\u2029", "\\u2029")
+    )
+
+
+def load_event(line: str) -> Event:
+    try:
+        return _ADAPTER.validate_json(line)
+    except (json.JSONDecodeError, ValidationError) as exc:
+        raise BaseError(f"malformed event: {line[:100]}") from exc
+
+
+class EventLog(BaseModel):
+    path: _Path
+    _lock: asyncio.Lock = PrivateAttr(default_factory=asyncio.Lock)
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    async def append(self, event: Event) -> None:
+        async with self._lock:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            with self.path.open("a", encoding="utf-8") as f:
+                f.write(dump_event(event) + "\n")
+
+    async def tail(self, n: int) -> list[Event]:
+        if not self.path.exists():
+            return []
+        window: deque[str] = deque(maxlen=n)
+        with self.path.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    window.append(line)
+        return [load_event(line) for line in window]
+
+    async def last(self) -> Event | None:
+        tail = await self.tail(1)
+        return tail[0] if tail else None