turnloop 0.1.0__py3-none-any.whl

turnloop/__init__.py

@@ -0,0 +1,3 @@
+"""turnloop — a local-first agentic coding harness."""
+
+__version__ = "0.1.0"

turnloop/__main__.py

@@ -0,0 +1,4 @@
+from turnloop.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

turnloop/agent/factory.py

@@ -0,0 +1,175 @@
+"""Wiring one configured agent together.
+
+Every entry point — TUI, headless, experiments, subagents — goes through here, so
+there is exactly one place where "what a session consists of" is defined. When the
+TUI and the experiment runner disagree about setup, the measurements stop meaning
+anything.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import anyio
+
+from turnloop.agent.loop import AgentLoop
+from turnloop.agent.system_prompt import build_system
+from turnloop.config import Settings
+from turnloop.context.compaction import Compactor
+from turnloop.mcp.client import MCPManager
+from turnloop.permissions.engine import PermissionEngine
+from turnloop.providers.base import Provider
+from turnloop.providers.registry import build_provider
+from turnloop.sessions.models import Session
+from turnloop.sessions.store import SessionStore, default_project_dir
+from turnloop.tools.base import ToolRegistry
+from turnloop.tools.builtin import build_registry, skills_segment
+from turnloop.tui.bridge import UIChannel
+
+# One limiter per (provider name, model) for the whole process. This is what makes
+# a subagent fan-out respect vLLM's --max-num-seqs rather than queueing 30
+# requests at a server configured for 16.
+_LIMITERS: dict[str, anyio.CapacityLimiter] = {}
+
+
+def limiter_for(provider: Provider) -> anyio.CapacityLimiter:
+    key = f"{provider.name}:{provider.model}"
+    if key not in _LIMITERS:
+        _LIMITERS[key] = anyio.CapacityLimiter(max(1, provider.caps.max_concurrent_requests))
+    return _LIMITERS[key]
+
+
+@dataclass
+class Agent:
+    loop: AgentLoop
+    provider: Provider
+    session: Session
+    registry: ToolRegistry
+    permissions: PermissionEngine
+    store: SessionStore | None
+    mcp: MCPManager | None = None
+
+    async def aclose(self) -> None:
+        await self.loop.aclose()
+        if self.mcp is not None:
+            await self.mcp.aclose()
+        if self.store is not None:
+            self.store.close()
+
+    async def start(self) -> dict[str, bool]:
+        """Connect MCP servers and fire SessionStart hooks.
+
+        Separate from construction because both touch the network and the
+        filesystem, and construction has to stay synchronous for the TUI's
+        __init__. Callers that skip it simply get no MCP tools.
+        """
+        results: dict[str, bool] = {}
+        if self.mcp is not None:
+            results = await self.mcp.connect_all()
+            from turnloop.mcp.adapter import adapters_for
+
+            for adapter in adapters_for(self.mcp):
+                self.registry.add(adapter)
+
+        if self.loop.hooks is not None:
+            await self.loop.hooks.run_session_event("SessionStart")  # type: ignore[attr-defined]
+        return results
+
+
+def create_agent(
+    settings: Settings,
+    cwd: Path,
+    ui: UIChannel,
+    *,
+    persist: bool = True,
+    resume: str | None = None,
+    provider: Provider | None = None,
+    system_variant: str | None = None,
+    compaction_strategy: str | None = None,
+) -> Agent:
+    provider = provider or build_provider(settings.provider, settings.provider_config())
+    registry = build_registry(settings, cwd)
+    permissions = PermissionEngine.from_config(
+        settings.permissions, settings.permission_mode, settings.project_root, cwd
+    )
+
+    session: Session | None = None
+    store: SessionStore | None = None
+    if resume:
+        session = SessionStore.resume(settings.project_root, resume)
+        if session is not None:
+            store = session.store  # type: ignore[assignment]
+    if session is None:
+        session = Session(
+            provider=settings.provider, model=provider.model, cwd=str(cwd)
+        )
+        if persist:
+            default_project_dir(settings.project_root)
+            store = SessionStore.attach(session, settings.project_root)
+
+    system = build_system(
+        settings=settings,
+        cwd=cwd,
+        registry=registry,
+        caps=provider.caps,
+        mode=settings.permission_mode,
+        variant=system_variant,
+    )
+    if skills := skills_segment(registry):
+        system.append(skills)
+
+    compactor = Compactor(
+        config=settings.compaction,
+        max_context=provider.caps.max_context,
+        provider=provider,
+        ui=ui,
+        strategy=compaction_strategy or "summarize",  # type: ignore[arg-type]
+    )
+
+    hooks = None
+    if settings.hooks:
+        from turnloop.hooks.runner import HookRunner
+
+        hooks = HookRunner(settings, cwd, session.session_id)
+
+    mcp = None
+    if any(cfg.enabled for cfg in settings.mcp_servers.values()):
+        mcp = MCPManager(settings.mcp_servers)
+
+    loop = AgentLoop(
+        provider=provider,
+        registry=registry,
+        session=session,
+        permissions=permissions,
+        settings=settings,
+        ui=ui,
+        cwd=cwd,
+        compactor=compactor,
+        hooks=hooks,
+        system=system,
+        limiter=limiter_for(provider),
+    )
+
+    # Tools that need to reach the agent itself (Task spawning a child, WebFetch
+    # summarizing a page) get it through extras rather than through imports, so
+    # the dependency stays one-directional.
+    loop._extras.update(
+        {
+            "provider": provider,
+            "registry": registry,
+            "ui": ui,
+            "limiter": loop.limiter,
+            "settings": settings,
+        }
+    )
+
+    return Agent(
+        loop=loop,
+        provider=provider,
+        session=session,
+        registry=registry,
+        permissions=permissions,
+        store=store,
+        mcp=mcp,
+    )

turnloop/agent/headless.py

@@ -0,0 +1,150 @@
+"""Headless execution: `turnloop -p "..."`.
+
+Exists for three audiences, in ascending order of how much this project depends on
+it: humans scripting the tool, CI, and the experiment runner. Being able to run a
+full agent turn with no terminal is what makes the measurements reproducible.
+
+`--json` emits one JSON object per event, so the output is parseable rather than
+scraped.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+
+from turnloop.agent.factory import create_agent
+from turnloop.config import Settings
+from turnloop.core.events import (
+    CompactionHappened,
+    ProviderStatus,
+    TextDelta,
+    ToolFinished,
+    ToolStarted,
+    UIEvent,
+)
+from turnloop.permissions.engine import PermissionDecision, PermissionRequest, Scope
+from turnloop.tui.bridge import UIChannel
+
+
+class PrintChannel(UIChannel):
+    """Streams to stdout. Declines every permission prompt, loudly.
+
+    Auto-approving in a non-interactive session would mean `turnloop -p` silently
+    running whatever a model asked for. Denying instead produces an error result
+    the model can react to, and tells the user which rule would have allowed it.
+    """
+
+    def __init__(self, json_mode: bool = False, quiet: bool = False,
+                 auto_approve: bool = False):
+        self.json_mode = json_mode
+        self.quiet = quiet
+        self.auto_approve = auto_approve
+        self.declined: list[str] = []
+        self._in_text = False
+
+    async def send(self, event: UIEvent) -> None:
+        if self.json_mode:
+            self._emit_json(event)
+            return
+        if self.quiet:
+            if isinstance(event, TextDelta):
+                sys.stdout.write(event.text)
+                sys.stdout.flush()
+            return
+
+        if isinstance(event, TextDelta):
+            sys.stdout.write(event.text)
+            sys.stdout.flush()
+            self._in_text = True
+            return
+
+        if isinstance(event, ToolStarted):
+            self._break()
+            print(f"  · {event.summary}", file=sys.stderr)
+        elif isinstance(event, ToolFinished):
+            if event.is_error:
+                print(f"  ! {event.name} failed", file=sys.stderr)
+        elif isinstance(event, ProviderStatus):
+            self._break()
+            print(f"  … {event.text}", file=sys.stderr)
+        elif isinstance(event, CompactionHappened):
+            self._break()
+            print(
+                f"  ⤺ compacted ({event.tier}): "
+                f"{event.tokens_before:,} → {event.tokens_after:,} tokens",
+                file=sys.stderr,
+            )
+
+    def _break(self) -> None:
+        if self._in_text:
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+            self._in_text = False
+
+    def _emit_json(self, event: UIEvent) -> None:
+        payload = asdict(event) if is_dataclass(event) else {"repr": repr(event)}
+        print(
+            json.dumps({"event": type(event).__name__, **payload}, default=str),
+            flush=True,
+        )
+
+    async def ask(self, request: PermissionRequest) -> PermissionDecision:
+        if self.auto_approve:
+            return PermissionDecision(approved=True, scope=Scope.ONCE)
+        self.declined.append(request.summary)
+        print(
+            f"  ✗ needs approval, declined (non-interactive): {request.summary}\n"
+            f"    allow it with: permissions.allow += [\"{request.suggested_rule}\"]",
+            file=sys.stderr,
+        )
+        return PermissionDecision(
+            approved=False,
+            reason=(
+                "This is a non-interactive session, so nobody can approve tool calls. "
+                f"Either avoid this call or tell the user to add the rule "
+                f"{request.suggested_rule!r} to their settings."
+            ),
+        )
+
+
+async def run_headless(settings: Settings, cwd: Path, prompt: str, json_mode: bool,
+                       resume: str | None = None, auto_approve: bool = False) -> int:
+    channel = PrintChannel(json_mode=json_mode, auto_approve=auto_approve)
+    agent = create_agent(settings, cwd, channel, resume=resume)
+
+    try:
+        await agent.start()  # MCP connect + SessionStart hooks
+        result = await agent.loop.run_turn(prompt)
+    except Exception as exc:  # noqa: BLE001 - a CLI must not traceback at the user
+        print(f"\nerror: {exc}", file=sys.stderr)
+        return 1
+    finally:
+        await agent.aclose()
+
+    if not json_mode:
+        print()
+        cost = agent.session.cost
+        parts = [
+            f"{cost.usage.input_tokens:,} in",
+            f"{cost.usage.output_tokens:,} out",
+        ]
+        if cost.cost_usd:
+            parts.append(f"${cost.cost_usd:.4f}")
+        if (gpu := agent.provider.gpu_seconds()) is not None:
+            hourly = agent.provider.caps.cost_per_hour
+            parts.append(f"GPU {gpu / 60:.1f} min ≈ ${gpu / 3600 * hourly:.2f}")
+        print(f"[{' · '.join(parts)}]", file=sys.stderr)
+
+        if agent.provider.caps.cost_per_hour and agent.provider.first_request_at:
+            # This endpoint bills by the hour and scales down only after ten idle
+            # minutes. Not saying this is how a $18/hr GPU stays up overnight.
+            print(
+                "\nThe self-hosted endpoint is still running. Stop it when you are done:\n"
+                "  modal app stop glm-5-2-serve",
+                file=sys.stderr,
+            )
+
+    return 0 if result is not None else 1