turnloop 0.1.0__py3-none-any.whl

turnloop/tools/write.py

@@ -0,0 +1,97 @@
+"""Write — full-file replacement, guarded by read-before-write."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from turnloop.tools.base import Tool, ToolContext, ToolOutput
+from turnloop.tools.textio import detect_newline, has_bom, read_text, write_text
+
+
+class WriteArgs(BaseModel):
+    file_path: str = Field(description="Absolute or project-relative path to write.")
+    content: str = Field(description="The complete new contents of the file.")
+
+
+class WriteTool(Tool):
+    name = "Write"
+    Args = WriteArgs
+    read_only = False
+    parallel_safe = False
+
+    descriptions = {
+        "terse": """
+Overwrite a file with `content`. Read it first if it exists. Prefer Edit for
+changes to existing files.
+""",
+        "normal": """
+Write a complete file, creating it or overwriting it.
+
+- If the file exists you must Read it first, and it must not have changed on disk
+  since. This prevents silently destroying content you never saw.
+- Prefer Edit for modifying an existing file. Write replaces everything, which
+  loses anything you did not reproduce exactly.
+- Parent directories are created as needed.
+- The file's existing newline style is preserved when overwriting.
+""",
+        "verbose": """
+Write a complete file, creating it if absent or overwriting it if present.
+
+Arguments:
+- `file_path`: absolute, or relative to the working directory.
+- `content`: the entire new contents. Not a patch, not a fragment.
+
+Constraints:
+- Overwriting requires a prior Read of that file in this session, and the file
+  must be unchanged on disk since that Read. If it changed, Read it again first.
+  This is what stops a full-file write from discarding content you never saw.
+- Prefer Edit when modifying an existing file. Write is appropriate for new
+  files, or when the change is a genuine rewrite.
+- Parent directories are created automatically.
+- Newline style (LF vs CRLF) is preserved from the existing file, so writing to a
+  CRLF repository does not produce a diff on every line.
+- Do not use Write to create documentation, summaries, or notes unless the user
+  asked for a file. Answer in the conversation instead.
+""",
+    }
+
+    async def run(self, args: WriteArgs, ctx: ToolContext) -> ToolOutput:
+        path = ctx.resolve(args.file_path)
+
+        if ctx.readonly:
+            return ToolOutput.error("plan mode is read-only; Write is not available")
+        if not ctx.within_allowed(path):
+            return ToolOutput.error(f"{path} is outside the project root ({ctx.root}).")
+        if path.is_dir():
+            return ToolOutput.error(f"{path} is a directory.")
+
+        existed = path.exists()
+        if existed:
+            if not ctx.files.has_read(path):
+                return ToolOutput.error(
+                    f"{path} exists but has not been read in this session. "
+                    "Read it first so the overwrite does not discard content."
+                )
+            if ctx.files.is_stale(path):
+                return ToolOutput.error(
+                    f"{path} changed on disk since you read it. Read it again, then retry."
+                )
+
+        newline = detect_newline(path) if existed else None
+        keep_bom = has_bom(path) if existed else False
+        previous_lines = len(read_text(path).splitlines()) if existed else 0
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        write_text(path, args.content, newline=newline, bom=keep_bom)
+        ctx.files.record_write(path, args.content)
+
+        new_lines = len(args.content.splitlines())
+        verb = "Updated" if existed else "Created"
+        return ToolOutput(
+            content=f"{verb} {path} ({new_lines} lines).",
+            display=f"{verb} {path.name} ({previous_lines} → {new_lines} lines)",
+            metrics={"created": not existed, "lines": new_lines, "bytes": len(args.content)},
+        )
+
+    def summary(self, args: WriteArgs) -> str:  # type: ignore[override]
+        return f"Write {args.file_path}"

turnloop/tui/app.py

@@ -0,0 +1,330 @@
+"""The Textual application.
+
+Concurrency, stated once:
+
+* `_agent_worker` owns the agent loop. It never touches a widget.
+* `_pump_worker` drains the event stream and calls widget methods. It never awaits
+  the model.
+* `_permission_worker` drains permission requests, pushes a modal, and sends the
+  answer back through the request's one-shot reply stream — which is what the
+  agent's task is parked on.
+
+All three are Textual asyncio workers on the same event loop, so there are no
+thread-safety questions, and cancelling the agent worker propagates straight into
+the in-flight HTTP stream and any child process.
+
+Typing during a turn is allowed. A message submitted mid-turn is queued and
+delivered as a steering turn once the current one finishes, because the useful
+moment to redirect an agent is exactly while it is going the wrong way.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import anyio
+from textual import work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Vertical
+from textual.widgets import Footer, Input
+from textual.worker import Worker
+
+from turnloop.agent.factory import create_agent
+from turnloop.config import Settings
+from turnloop.core.events import (
+    CompactionHappened,
+    ProviderStatus,
+    StatusUpdate,
+    TextDelta,
+    ThinkingDelta,
+    ToolFinished,
+    ToolProgress,
+    ToolStarted,
+    TurnFinished,
+    UIEvent,
+)
+from turnloop.tui.bridge import PendingPermission, StreamChannel
+from turnloop.tui.widgets.permission import ChoiceModal, PermissionModal
+from turnloop.tui.widgets.status import BootPanel, StatusBar
+from turnloop.tui.widgets.transcript import Transcript
+
+
+class TurnloopApp(App):
+    CSS_PATH = "app.tcss"
+    TITLE = "turnloop"
+
+    BINDINGS = [
+        Binding("ctrl+c", "interrupt", "Interrupt", priority=True),
+        Binding("ctrl+d", "quit", "Quit", priority=True),
+        # priority=True is required: the focused Input claims these keys otherwise,
+        # and the prompt always has focus.
+        Binding("ctrl+p", "cycle_mode", "Permission mode", priority=True),
+        Binding("ctrl+l", "clear", "Clear view", priority=True),
+    ]
+
+    def __init__(self, settings: Settings, cwd: Path, resume: str | None = None):
+        super().__init__()
+        self.settings = settings
+        self.cwd = cwd
+        self.resume_id = resume
+        self.exit_code = 0
+
+        self.channel, self._events, self._permissions = StreamChannel.create()
+        self.agent = create_agent(settings, cwd, self.channel, resume=resume)
+        self._queued: list[str] = []
+        self._busy = False
+        self._agent_worker: Worker | None = None
+
+    # --- layout -----------------------------------------------------------
+
+    def compose(self) -> ComposeResult:
+        with Vertical():
+            yield Transcript(id="transcript")
+            yield BootPanel(id="boot")
+            yield StatusBar(id="status")
+            yield Input(placeholder="Ask, or /help", id="prompt")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one("#boot", BootPanel).display = False
+        status = self.query_one(StatusBar)
+        status.provider = self.agent.provider.name
+        status.model = self.agent.provider.model
+        status.mode = self.settings.permission_mode
+        status.cost_per_hour = self.agent.provider.caps.cost_per_hour
+        status.context_max = self.agent.provider.caps.max_context
+
+        self._pump_worker()
+        self._permission_worker()
+        self._startup_worker()
+
+        transcript = self.query_one(Transcript)
+        banner = (
+            f"turnloop · {self.agent.provider.name}:{self.agent.provider.model} · "
+            f"{self.cwd}"
+        )
+        self.call_later(transcript.add_note, banner)
+        if self.resume_id and self.agent.session.messages:
+            self.call_later(
+                transcript.add_note,
+                f"resumed {self.agent.session.session_id} "
+                f"({len(self.agent.session.messages)} messages)",
+            )
+        if self.agent.provider.caps.cost_per_hour:
+            self.call_later(
+                transcript.add_note,
+                f"this provider bills ${self.agent.provider.caps.cost_per_hour:.2f}/hour of "
+                "wall clock; the first request may cold-boot for ~29 minutes",
+            )
+        self.query_one(Input).focus()
+
+    # --- input ------------------------------------------------------------
+
+    async def on_input_submitted(self, event: Input.Submitted) -> None:
+        text = event.value.strip()
+        event.input.value = ""
+        if not text:
+            return
+
+        if text.startswith("/"):
+            await self._handle_command(text)
+            return
+
+        transcript = self.query_one(Transcript)
+        await transcript.add_user(text)
+
+        if self._busy:
+            # Steering: delivered after the current turn's tool batch completes.
+            self._queued.append(text)
+            await transcript.add_note("queued — will be sent when the current turn finishes")
+            return
+
+        self._start_turn(text)
+
+    def _start_turn(self, prompt: str) -> None:
+        self._busy = True
+        self._agent_worker = self.run_worker(
+            self._run_turn(prompt), exclusive=False, thread=False, name="agent"
+        )
+
+    async def _run_turn(self, prompt: str) -> None:
+        transcript = self.query_one(Transcript)
+        try:
+            await self.agent.loop.run_turn(prompt)
+        except anyio.get_cancelled_exc_class():
+            await transcript.add_note("interrupted")
+            raise
+        except Exception as exc:  # noqa: BLE001 - a failed turn must not kill the app
+            await transcript.add_error(f"error: {exc}")
+        finally:
+            self._busy = False
+            await transcript.end_message()
+
+        if self._queued:
+            self._start_turn(self._queued.pop(0))
+
+    # --- workers ----------------------------------------------------------
+
+    @work(exclusive=False, thread=False, name="pump")
+    async def _pump_worker(self) -> None:
+        transcript = self.query_one(Transcript)
+        status = self.query_one(StatusBar)
+        boot = self.query_one("#boot", BootPanel)
+
+        async with self._events:
+            async for event in self._events:
+                await self._render(event, transcript, status, boot)
+
+    async def _render(self, event: UIEvent, transcript: Transcript, status: StatusBar,
+                      boot: BootPanel) -> None:
+        if isinstance(event, TextDelta):
+            transcript.append_delta(event.text)
+        elif isinstance(event, ThinkingDelta):
+            transcript.append_thinking(event.text)
+        elif isinstance(event, ToolStarted):
+            await transcript.add_tool_start(event.tool_use_id, event.summary, event.subagent_id)
+        elif isinstance(event, ToolProgress):
+            transcript.tool_progress(event.tool_use_id, event.text)
+        elif isinstance(event, ToolFinished):
+            transcript.update_tool(
+                event.tool_use_id, event.name, event.is_error, event.display, event.duration_s
+            )
+        elif isinstance(event, ProviderStatus):
+            if event.phase == "cold_boot":
+                boot.show(event.text, event.elapsed_s)
+            else:
+                boot.hide()
+                if event.phase == "retrying":
+                    await transcript.add_note(event.text)
+        elif isinstance(event, StatusUpdate):
+            boot.hide()
+            status.context_tokens = event.context_tokens
+            status.context_max = max(1, event.context_max)
+            status.cost_usd = event.cost_usd
+            status.tokens_in = event.usage.input_tokens
+            status.tokens_out = event.usage.output_tokens
+            if event.gpu_seconds is not None:
+                status.gpu_seconds = event.gpu_seconds
+        elif isinstance(event, CompactionHappened):
+            await transcript.add_note(
+                f"context compacted ({event.tier}): "
+                f"{event.tokens_before:,} → {event.tokens_after:,} tokens"
+            )
+        elif isinstance(event, TurnFinished):
+            await transcript.end_message()
+
+    @work(exclusive=False, thread=False, name="startup")
+    async def _startup_worker(self) -> None:
+        """Connect MCP servers after the UI is up.
+
+        Doing this in __init__ would mean a slow or hanging MCP server delays the
+        first frame, which reads as a broken application.
+        """
+        results = await self.agent.start()
+        if not results or self.agent.mcp is None:
+            return
+        transcript = self.query_one(Transcript)
+        for name, ok in sorted(results.items()):
+            client = self.agent.mcp.clients[name]
+            detail = f"{len(client.tools)} tool(s)" if ok else f"unavailable ({client.error})"
+            await transcript.add_note(f"mcp {name}: {detail}")
+
+    @work(exclusive=False, thread=False, name="permissions")
+    async def _permission_worker(self) -> None:
+        async with self._permissions:
+            async for pending in self._permissions:
+                await self._resolve_permission(pending)
+
+    async def _resolve_permission(self, pending: PendingPermission) -> None:
+        request = pending.request
+        modal = (
+            ChoiceModal(request)
+            if request.tool_name == "AskUserQuestion"
+            else PermissionModal(request)
+        )
+        decision = await self.push_screen_wait(modal)
+        if decision.approved and decision.rule and decision.scope.value == "project":
+            self._persist_rule(decision.rule)
+        await pending.answer(decision)
+
+    def _persist_rule(self, rule: str) -> None:
+        """Append an allow rule to settings.local.json.
+
+        Local rather than shared: a permission the user granted on their machine is
+        not automatically one their teammates want committed.
+        """
+        import json
+
+        path = self.settings.project_root / ".turnloop" / "settings.local.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            data = json.loads(path.read_text(encoding="utf-8")) if path.is_file() else {}
+        except json.JSONDecodeError:
+            data = {}
+        permissions = data.setdefault("permissions", {})
+        allow = permissions.setdefault("allow", [])
+        if rule not in allow:
+            allow.append(rule)
+        path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    # --- commands ---------------------------------------------------------
+
+    async def _handle_command(self, text: str) -> None:
+        from turnloop.commands.dispatch import CommandOutcome, dispatch_command
+
+        transcript = self.query_one(Transcript)
+        outcome: CommandOutcome = await dispatch_command(text, self.agent, self.settings, self.cwd)
+
+        if outcome.message:
+            await transcript.add_note(outcome.message)
+        if outcome.quit:
+            self.exit()
+            return
+        if outcome.clear:
+            await transcript.remove_children()
+            await transcript.add_note("view cleared")
+        if outcome.mode:
+            self.settings.permission_mode = outcome.mode
+            self.agent.permissions.mode = outcome.mode
+            self.query_one(StatusBar).mode = outcome.mode
+        if outcome.prompt:
+            await transcript.add_user(outcome.prompt if outcome.echo else text)
+            if self._busy:
+                self._queued.append(outcome.prompt)
+            else:
+                self._start_turn(outcome.prompt)
+
+    # --- actions ----------------------------------------------------------
+
+    def action_interrupt(self) -> None:
+        if self._agent_worker is not None and self._busy:
+            self._agent_worker.cancel()
+            self._busy = False
+        else:
+            self.exit()
+
+    def action_cycle_mode(self) -> None:
+        order = ["default", "plan", "auto", "bypass"]
+        current = order.index(self.settings.permission_mode)
+        mode = order[(current + 1) % len(order)]
+        self.settings.permission_mode = mode  # type: ignore[assignment]
+        self.agent.permissions.mode = mode  # type: ignore[assignment]
+        self.query_one(StatusBar).mode = mode
+
+    async def action_clear(self) -> None:
+        await self.query_one(Transcript).remove_children()
+
+    # --- teardown ---------------------------------------------------------
+
+    async def on_unmount(self) -> None:
+        await self.agent.aclose()
+        provider = self.agent.provider
+        if provider.caps.cost_per_hour and provider.first_request_at:
+            gpu = provider.gpu_seconds() or 0
+            print(
+                f"\nThe self-hosted endpoint is still running "
+                f"({gpu / 60:.1f} min ≈ ${gpu / 3600 * provider.caps.cost_per_hour:.2f} so far).\n"
+                f"It scales down after 10 idle minutes, or stop it now:\n"
+                f"  modal app stop glm-5-2-serve"
+            )

turnloop/tui/app.tcss

@@ -0,0 +1,84 @@
+Screen {
+    layers: base modal;
+}
+
+#transcript {
+    height: 1fr;
+    padding: 0 1;
+    scrollbar-size-vertical: 1;
+}
+
+.msg {
+    margin-bottom: 1;
+}
+
+.msg.user {
+    color: $text;
+    background: $boost;
+    padding: 0 1;
+}
+
+.msg.assistant {
+    color: $text;
+}
+
+.msg.thinking {
+    color: $text-muted;
+    padding-left: 2;
+}
+
+.msg.thinking.collapsed {
+    display: none;
+}
+
+.msg.tool {
+    padding-left: 1;
+    margin-bottom: 0;
+}
+
+.msg.note {
+    color: $text-muted;
+}
+
+.msg.error {
+    color: $error;
+}
+
+#boot {
+    display: none;
+    height: auto;
+    padding: 1 2;
+    border: round $warning;
+    margin: 1 2;
+}
+
+#status {
+    height: 1;
+    background: $panel;
+    color: $text-muted;
+}
+
+#prompt {
+    border: none;
+    border-top: solid $primary;
+    height: 3;
+}
+
+#permission-box {
+    layer: modal;
+    width: 80%;
+    max-width: 100;
+    height: auto;
+    max-height: 80%;
+    padding: 1 2;
+    border: round $warning;
+    background: $surface;
+}
+
+#permission-body {
+    height: auto;
+}
+
+#permission-keys {
+    height: auto;
+}

turnloop/tui/bridge.py

@@ -0,0 +1,142 @@
+"""The boundary between the agent loop and whatever is displaying it.
+
+One rule, and the entire concurrency design follows from it:
+
+    **The agent loop never touches a widget, and the UI never awaits the model.**
+
+Communication is one memory object stream outbound (events) and one one-shot
+stream per permission request inbound (the answer). The loop's task parks on
+`ask()` while the UI keeps repainting, handling keystrokes and streaming the tool
+output that is already on screen.
+
+Three implementations share this interface: the Textual app, the headless printer,
+and a null channel for tests and experiments.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+import anyio
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+
+from turnloop.core.events import UIEvent
+from turnloop.permissions.engine import PermissionDecision, PermissionRequest, Scope
+
+
+@dataclass(slots=True)
+class PendingPermission:
+    request: PermissionRequest
+    reply_send: MemoryObjectSendStream[PermissionDecision]
+    reply_recv: MemoryObjectReceiveStream[PermissionDecision]
+
+    @classmethod
+    def create(cls, request: PermissionRequest) -> PendingPermission:
+        send, recv = anyio.create_memory_object_stream[PermissionDecision](1)
+        return cls(request=request, reply_send=send, reply_recv=recv)
+
+    async def answer(self, decision: PermissionDecision) -> None:
+        await self.reply_send.send(decision)
+
+    async def wait(self) -> PermissionDecision:
+        return await self.reply_recv.receive()
+
+
+class UIChannel(ABC):
+    """What the agent loop is given instead of a display."""
+
+    @abstractmethod
+    async def send(self, event: UIEvent) -> None: ...
+
+    @abstractmethod
+    async def ask(self, request: PermissionRequest) -> PermissionDecision: ...
+
+    def for_subagent(self, subagent_id: str) -> UIChannel:
+        """A channel that tags everything with a subagent id.
+
+        Subagent output has to be visually separable — a fan-out of three children
+        interleaving into one transcript is unreadable — and its permission
+        prompts must still reach the one modal the parent owns.
+        """
+        return TaggedChannel(self, subagent_id)
+
+
+@dataclass
+class TaggedChannel(UIChannel):
+    inner: UIChannel
+    subagent_id: str
+
+    async def send(self, event: UIEvent) -> None:
+        if hasattr(event, "subagent_id") and getattr(event, "subagent_id", None) is None:
+            try:
+                object.__setattr__(event, "subagent_id", self.subagent_id)
+            except AttributeError:  # slots without the field
+                pass
+        await self.inner.send(event)
+
+    async def ask(self, request: PermissionRequest) -> PermissionDecision:
+        request.subagent_id = self.subagent_id
+        return await self.inner.ask(request)
+
+
+@dataclass
+class StreamChannel(UIChannel):
+    """Pushes events into a memory stream. Used by the Textual app.
+
+    The send stream is buffered: a burst of token deltas must not block the agent
+    loop waiting for the UI to catch up, and if the buffer does fill, dropping
+    display events is better than stalling model consumption.
+    """
+
+    events: MemoryObjectSendStream[UIEvent]
+    permissions: MemoryObjectSendStream[PendingPermission]
+
+    async def send(self, event: UIEvent) -> None:
+        try:
+            self.events.send_nowait(event)
+        except anyio.WouldBlock:
+            # Buffer full: wait, but only briefly. A permanently stuck UI should
+            # not hang the model stream.
+            with anyio.move_on_after(1.0):
+                await self.events.send(event)
+        except anyio.BrokenResourceError:
+            pass  # UI is gone; the loop is being torn down
+
+    async def ask(self, request: PermissionRequest) -> PermissionDecision:
+        pending = PendingPermission.create(request)
+        await self.permissions.send(pending)
+        return await pending.wait()
+
+    @staticmethod
+    def create(buffer: int = 4096):
+        ev_send, ev_recv = anyio.create_memory_object_stream[UIEvent](buffer)
+        pm_send, pm_recv = anyio.create_memory_object_stream[PendingPermission](8)
+        return StreamChannel(events=ev_send, permissions=pm_send), ev_recv, pm_recv
+
+
+@dataclass
+class NullChannel(UIChannel):
+    """Discards output; auto-answers permission prompts.
+
+    Used by experiments and tests. `auto_approve=False` is the interesting
+    setting: it exercises the denial path, which is how the permission-safety
+    grader checks that plan mode and deny rules actually hold.
+    """
+
+    auto_approve: bool = True
+    seen: list[UIEvent] = field(default_factory=list)
+    asked: list[PermissionRequest] = field(default_factory=list)
+    record: bool = False
+
+    async def send(self, event: UIEvent) -> None:
+        if self.record:
+            self.seen.append(event)
+
+    async def ask(self, request: PermissionRequest) -> PermissionDecision:
+        self.asked.append(request)
+        return PermissionDecision(
+            approved=self.auto_approve,
+            scope=Scope.ONCE,
+            reason="" if self.auto_approve else "non-interactive session",
+        )