letscode 0.1.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

letscode/__main__.py

@@ -0,0 +1,13 @@
+"""Enable ``python -m letscode`` (same entry point as the console script).
+
+``letscode`` is a PEP 420 namespace package (no ``__init__.py`` by
+design), so this dunder file trips INP001 — silenced with rationale.
+"""
+# ruff: noqa: INP001  # intentional namespace package; see module docstring
+
+from __future__ import annotations
+
+from letscode.cli.app import main
+
+if __name__ == "__main__":
+    main()

letscode/agent/agent.py

@@ -0,0 +1,181 @@
+"""Agent class — imperative wrapper around ``agent_loop``.
+
+Constructed with an ``AgentState``, an ``LLMStream``, and optionally a
+``PluginManager`` (T21). Driven via ``prompt(text)``; listeners attached
+via ``subscribe()`` fire on every emitted event; the optional
+``PluginManager``'s ``letscode_on_event`` hook fires for the same events.
+``wait_for_idle()`` returns when no run is in progress; ``abort()``
+signals cancellation via a shared ``asyncio.Event``.
+
+T05 scope: no steering or follow-up queues. M6 adds them.
+
+See design section 3.5.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import time
+import uuid
+from typing import TYPE_CHECKING
+
+from letscode.agent.execution_env import LocalEnv
+from letscode.agent.hooks import call_async_hook
+from letscode.agent.loop import agent_loop
+from letscode.agent.messages import UserMessage
+from letscode.llm.types import TextPart
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Sequence
+
+    from letscode.agent.events import Event
+    from letscode.agent.execution_env import ExecutionEnv
+    from letscode.agent.loop import LLMStream
+    from letscode.agent.messages import AgentMessage
+    from letscode.agent.state import AgentState
+    from letscode.plugins.manager import PluginManager
+
+
+class Agent:
+    """Application-facing handle to drive one agent session."""
+
+    def __init__(
+        self,
+        state: AgentState,
+        llm: LLMStream,
+        pm: PluginManager | None = None,
+        *,
+        env: ExecutionEnv | None = None,
+    ) -> None:
+        self.state = state
+        self._llm = llm
+        self._pm = pm
+        self._env: ExecutionEnv = env if env is not None else LocalEnv()
+        self._subscribers: list[Callable[[Event], Awaitable[None] | None]] = []
+        self._cancel_event = asyncio.Event()
+        self._idle_event = asyncio.Event()
+        self._idle_event.set()
+
+    def subscribe(
+        self, callback: Callable[[Event], Awaitable[None] | None]
+    ) -> Callable[[], None]:
+        """Register ``callback`` to fire for every emitted event.
+
+        Returns an unsubscribe handle. The callback may be sync or async.
+        Callbacks fire in registration order; the agent awaits each one
+        (including async ones) before continuing the loop.
+        """
+        self._subscribers.append(callback)
+
+        def _unsubscribe() -> None:
+            # Idempotent: a second call is a no-op rather than an error.
+            with contextlib.suppress(ValueError):
+                self._subscribers.remove(callback)
+
+        return _unsubscribe
+
+    async def prompt(self, text: str) -> None:
+        """Send one user message and run a single turn.
+
+        Returns only after ``agent_end`` listeners have all completed.
+        Raises ``RuntimeError`` if a run is already in progress.
+        """
+        if not self._idle_event.is_set():
+            msg = "Agent.prompt called while a run is in progress"
+            raise RuntimeError(msg)
+        user = UserMessage(
+            id=str(uuid.uuid4()),
+            content=[TextPart(text=text)],
+            timestamp=time.time(),
+        )
+        await self._run([user])
+
+    async def continue_(self) -> None:
+        """Resume the loop without adding a new user message (T31).
+
+        Frontends call this to retry after a recoverable
+        :class:`~letscode.llm.errors.ProviderError`. The agent re-enters
+        ``agent_loop`` with the existing ``state.messages`` and no new
+        inputs, which restarts the assistant turn that just failed.
+        """
+        if not self._idle_event.is_set():
+            msg = "Agent.continue_ called while a run is in progress"
+            raise RuntimeError(msg)
+        await self._run([])
+
+    def steer(self, text: str) -> None:
+        """Queue a user message to deliver at the next turn boundary (T40).
+
+        Safe to call mid-run, including from a different task. The
+        agent loop drains the queue after each ``TurnEnd`` event,
+        appending the queued text as a :class:`UserMessage` to
+        ``state.messages``. Delivery cadence is governed by
+        ``state.steering_mode`` — ``"one-at-a-time"`` (the default)
+        pops one per turn; ``"all"`` drains the whole queue.
+        """
+        self.state.steering_queue.append(text)
+
+    @property
+    def queued_steering(self) -> tuple[str, ...]:
+        """Read-only snapshot of pending steering messages."""
+        return tuple(self.state.steering_queue)
+
+    def follow_up(self, text: str) -> None:
+        """Queue a user message to deliver after the agent would otherwise end (T41).
+
+        Where ``steer`` injects between tool batches, ``follow_up``
+        injects at the point where the loop would emit ``AgentEnd``.
+        With a non-empty follow-up queue, the loop drains it (per
+        ``state.follow_up_mode``), appends each as a UserMessage, and
+        runs another turn instead of ending. Useful for "after this
+        finishes, also do X" interactions.
+        """
+        self.state.follow_up_queue.append(text)
+
+    @property
+    def queued_follow_up(self) -> tuple[str, ...]:
+        """Read-only snapshot of pending follow-up messages."""
+        return tuple(self.state.follow_up_queue)
+
+    async def wait_for_idle(self) -> None:
+        """Block until the agent has no active run."""
+        await self._idle_event.wait()
+
+    def abort(self) -> None:
+        """Signal the active run to cancel.
+
+        Sets the shared cancel event; the LLM client and the loop honor it
+        at the next checkpoint. No-op if no run is in progress.
+        """
+        self._cancel_event.set()
+
+    async def _run(self, inputs: Sequence[AgentMessage]) -> None:
+        self._cancel_event.clear()
+        self._idle_event.clear()
+        try:
+            async for event in agent_loop(
+                inputs,
+                self.state,
+                llm=self._llm,
+                cancel_event=self._cancel_event,
+                pm=self._pm,
+                env=self._env,
+            ):
+                await self._fire(event)
+        finally:
+            self._idle_event.set()
+
+    async def _fire(self, event: Event) -> None:
+        # Snapshot the list so subscribe/unsubscribe during firing is safe.
+        for callback in list(self._subscribers):
+            result = callback(event)
+            if inspect.isawaitable(result):
+                await result
+        # T21: also fire the plugin on_event hook.
+        if self._pm is not None:
+            await call_async_hook(
+                self._pm._pm.hook.letscode_on_event,  # noqa: SLF001
+                event=event,
+            )

letscode/agent/compaction.py

@@ -0,0 +1,273 @@
+"""Compaction primitives (T43).
+
+When a session approaches the model's context-window limit, *compaction*
+collapses the older portion into a single :class:`CustomMessage` summary
+so the conversation can keep going. The summary is produced by the LLM
+itself in a separate one-shot call.
+
+This module is the policy + the per-call machinery; T44 wires it into
+the agent loop's per-turn overflow check and exposes a ``/compact``
+slash command.
+
+Two-tier message model recap (T37): we drop the collapsed messages
+from ``state.messages`` and replace them with a single
+:class:`~letscode.agent.messages.CustomMessage` of kind ``"compaction"``.
+The built-in ``letscode_convert_to_llm`` hook expands that marker into a
+synthetic :class:`AssistantMessage` so the LLM sees its own internal
+summary on subsequent calls — the *transcript* (the JSONL on disk) is
+unchanged, the *LLM view* is compacted.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from letscode.agent.events import TextDelta
+from letscode.agent.messages import (
+    AssistantMessage,
+    CustomMessage,
+    ToolResultMessage,
+    UserMessage,
+)
+from letscode.llm.types import TextPart
+
+_TOOL_RESULT_TRUNCATE_CHARS = 1000
+"""Per-tool-result cap when rendering the conversation for summarisation —
+prevents an oversize tool log from blowing past the context window during
+the summary call itself."""
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from letscode.agent.loop import LLMStream
+    from letscode.agent.messages import AgentMessage
+    from letscode.agent.state import AgentState
+
+
+# ---------------------------------------------------------------------------
+# Policy
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CompactionPolicy:
+    """When + how aggressively to compact.
+
+    - ``threshold_ratio``: compact when the estimated input-token count
+      exceeds this fraction of the model's context window.
+    - ``keep_recent_messages``: always preserve the last N messages
+      uncollapsed so the assistant has clear local context.
+    - ``summary_system_prompt``: passed as the system prompt of the
+      summarisation call; overridable per-invocation in ``compact()``.
+    """
+
+    threshold_ratio: float = 0.8
+    keep_recent_messages: int = 4
+    summary_system_prompt: str = (
+        "You summarise prior conversation history concisely. Keep the "
+        "summary under 200 words, preserving file names, function names, "
+        "user goals, and any outstanding follow-ups. Do not invent details."
+    )
+
+
+DEFAULT_POLICY = CompactionPolicy()
+"""The default compaction policy used by the agent loop."""
+
+
+# ---------------------------------------------------------------------------
+# Token estimation
+# ---------------------------------------------------------------------------
+
+
+_CHARS_PER_TOKEN_APPROX = 4
+"""Rough rule of thumb (English text + JSON tool calls); imprecise but
+adequate for "are we approaching the limit" decisions."""
+
+
+def estimate_tokens(messages: Sequence[AgentMessage]) -> int:
+    """Approximate the token count of the LLM-visible portion of ``messages``.
+
+    Counts characters in :class:`TextPart` content plus a rough surcharge
+    for tool-call JSON. ``CustomMessage`` entries are skipped (they don't
+    reach the LLM unless a plugin expands them, and the expanded form is
+    counted on the next pass).
+    """
+    total_chars = 0
+    for m in messages:
+        if isinstance(m, CustomMessage):
+            continue
+        if isinstance(m, AssistantMessage):
+            for p in m.content:
+                if isinstance(p, TextPart):
+                    total_chars += len(p.text)
+            for tc in m.tool_calls:
+                # Tool calls serialise as JSON in the wire format.
+                total_chars += len(tc.name) + sum(
+                    len(str(v)) for v in tc.arguments.values()
+                )
+        elif isinstance(m, (UserMessage, ToolResultMessage)):
+            for p in m.content:
+                if isinstance(p, TextPart):
+                    total_chars += len(p.text)
+    return total_chars // _CHARS_PER_TOKEN_APPROX
+
+
+def should_compact(
+    state: AgentState,
+    *,
+    context_window: int,
+    policy: CompactionPolicy = DEFAULT_POLICY,
+) -> bool:
+    """Return ``True`` when token usage crosses ``policy.threshold_ratio``.
+
+    ``context_window`` is the model's input limit (e.g. from the footer's
+    :data:`MODEL_PRICES` table). A non-positive value short-circuits to
+    ``False`` — compaction needs a known window to be meaningful.
+    """
+    if context_window <= 0:
+        return False
+    if len(state.messages) <= policy.keep_recent_messages:
+        return False
+    used = estimate_tokens(state.messages)
+    return used > policy.threshold_ratio * context_window
+
+
+# ---------------------------------------------------------------------------
+# The compact() primitive
+# ---------------------------------------------------------------------------
+
+
+async def compact(
+    state: AgentState,
+    llm: LLMStream,
+    *,
+    policy: CompactionPolicy = DEFAULT_POLICY,
+    custom_summary_prompt: str | None = None,
+) -> CustomMessage | None:
+    """Collapse the older portion of ``state.messages`` into a summary.
+
+    Splits ``state.messages`` at ``-policy.keep_recent_messages``,
+    summarises the older slice via a one-shot LLM call, replaces it
+    with a single :class:`~letscode.agent.messages.CustomMessage` of
+    kind ``"compaction"``, and returns that marker.
+
+    Returns ``None`` if there's nothing to compact (the message list is
+    shorter than the keep-recent floor).
+
+    The summary call uses ``state.model`` — same provider, same context
+    window. Pass ``custom_summary_prompt`` to override the default
+    summarisation instructions for a specific call (e.g.
+    "focus on the auth flow"). Tool messages in the collapsed slice are
+    rendered as ``[tool result …]`` lines so the model still sees the
+    factual events it acted on.
+    """
+    if len(state.messages) <= policy.keep_recent_messages:
+        return None
+
+    to_summarise = state.messages[: -policy.keep_recent_messages]
+    kept = state.messages[-policy.keep_recent_messages :]
+
+    system_prompt = policy.summary_system_prompt
+    if custom_summary_prompt:
+        system_prompt = (
+            f"{system_prompt}\n\nAdditional instructions:\n{custom_summary_prompt}"
+        )
+
+    request_msg = _build_summary_request(to_summarise)
+    summary_text = await _stream_summary(
+        llm,
+        model=state.model,
+        system=system_prompt,
+        request=request_msg,
+    )
+
+    marker = CustomMessage(
+        id=str(uuid.uuid4()),
+        kind="compaction",
+        payload={
+            "summary": summary_text.strip(),
+            "collapsed_count": len(to_summarise),
+        },
+        timestamp=time.time(),
+    )
+    # Replace the collapsed slice with the marker; keep the rest as-is.
+    state.messages[:] = [marker, *kept]
+    return marker
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_summary_request(
+    messages: Sequence[AgentMessage],
+) -> list[UserMessage]:
+    """Render ``messages`` as a single user message asking for a summary."""
+    rendered = _render_conversation(messages)
+    body = (
+        "Summarise the following conversation between a user and an "
+        "AI coding assistant. Preserve file names, intent, and "
+        "outstanding work.\n\n--- BEGIN ---\n"
+        f"{rendered}\n--- END ---"
+    )
+    return [
+        UserMessage(
+            id="compaction-request",
+            content=[TextPart(text=body)],
+            timestamp=time.time(),
+        ),
+    ]
+
+
+def _render_conversation(messages: Sequence[AgentMessage]) -> str:
+    """Render a slice of the transcript as plain text for the summariser."""
+    lines: list[str] = []
+    for m in messages:
+        if isinstance(m, CustomMessage):
+            if m.kind == "compaction":
+                summary = str(m.payload.get("summary", "(empty)"))
+                lines.append(f"[earlier-summary]\n{summary}")
+            continue
+        if isinstance(m, UserMessage):
+            text = "".join(p.text for p in m.content if isinstance(p, TextPart))
+            lines.append(f"[user]\n{text}")
+        elif isinstance(m, AssistantMessage):
+            text = "".join(p.text for p in m.content if isinstance(p, TextPart))
+            tools = (
+                f" (tool calls: {', '.join(tc.name for tc in m.tool_calls)})"
+                if m.tool_calls
+                else ""
+            )
+            lines.append(f"[assistant{tools}]\n{text}")
+        elif isinstance(m, ToolResultMessage):
+            text = "".join(p.text for p in m.content if isinstance(p, TextPart))
+            # Cap individual tool outputs so the summary request itself
+            # doesn't blow past the context window.
+            if len(text) >= _TOOL_RESULT_TRUNCATE_CHARS:
+                text = text[:_TOOL_RESULT_TRUNCATE_CHARS] + " …(truncated)"
+            err = " (error)" if m.is_error else ""
+            lines.append(f"[tool-result{err}]\n{text}")
+    return "\n\n".join(lines)
+
+
+async def _stream_summary(
+    llm: LLMStream,
+    *,
+    model: str,
+    system: str,
+    request: list[UserMessage],
+) -> str:
+    """Drive the LLM through one summarisation turn, returning collected text."""
+    buffer: list[str] = []
+    async for stream_event in llm.stream(
+        model=model,
+        messages=request,
+        system=system,
+    ):
+        if isinstance(stream_event, TextDelta):
+            buffer.append(stream_event.delta)
+    return "".join(buffer)

letscode/agent/events.py

@@ -0,0 +1,163 @@
+"""Event and StreamEvent unions emitted by the agent loop.
+
+See design sections 1.4 and 1.5. Each event carries a ``type`` literal that
+discriminates the union; both unions round-trip through Pydantic JSON.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field
+
+from letscode.agent.messages import (  # noqa: TC001  # Pydantic resolves at runtime
+    AgentMessage,
+    AssistantMessage,
+    ToolResultMessage,
+)
+from letscode.agent.tools import (
+    ToolPartialResult,  # noqa: TC001  # Pydantic resolves at runtime
+)
+from letscode.llm.types import Usage  # noqa: TC001  # Pydantic resolves at runtime
+
+# ---------------------------------------------------------------------------
+# Stream events: deltas emitted while an assistant message is streaming.
+# ---------------------------------------------------------------------------
+
+
+class TextDelta(BaseModel):
+    type: Literal["text_delta"] = "text_delta"
+    delta: str
+
+
+class ThinkingDelta(BaseModel):
+    type: Literal["thinking_delta"] = "thinking_delta"
+    delta: str
+
+
+class ToolCallStart(BaseModel):
+    type: Literal["tool_call_start"] = "tool_call_start"
+    tool_call_id: str
+    name: str
+
+
+class ToolCallArgsDelta(BaseModel):
+    type: Literal["tool_call_args_delta"] = "tool_call_args_delta"
+    tool_call_id: str
+    delta: str
+
+
+class ToolCallEnd(BaseModel):
+    type: Literal["tool_call_end"] = "tool_call_end"
+    tool_call_id: str
+
+
+class UsageEvent(BaseModel):
+    type: Literal["usage"] = "usage"
+    usage: Usage
+
+
+class StopEvent(BaseModel):
+    type: Literal["stop"] = "stop"
+    reason: str
+
+
+StreamEvent = Annotated[
+    TextDelta
+    | ThinkingDelta
+    | ToolCallStart
+    | ToolCallArgsDelta
+    | ToolCallEnd
+    | UsageEvent
+    | StopEvent,
+    Field(discriminator="type"),
+]
+"""Discriminated union of streaming deltas, keyed by ``type``."""
+
+
+# ---------------------------------------------------------------------------
+# Agent loop events.
+# ---------------------------------------------------------------------------
+
+
+class AgentStart(BaseModel):
+    type: Literal["agent_start"] = "agent_start"
+    messages: list[AgentMessage]
+
+
+class AgentEnd(BaseModel):
+    type: Literal["agent_end"] = "agent_end"
+    messages: list[AgentMessage]
+    error: str | None = None
+
+
+class TurnStart(BaseModel):
+    type: Literal["turn_start"] = "turn_start"
+    turn: int
+
+
+class TurnEnd(BaseModel):
+    type: Literal["turn_end"] = "turn_end"
+    turn: int
+    message: AssistantMessage
+    tool_results: list[ToolResultMessage]
+
+
+class MessageStart(BaseModel):
+    type: Literal["message_start"] = "message_start"
+    message: AgentMessage
+
+
+class MessageUpdate(BaseModel):
+    """Emitted only for streaming assistant messages."""
+
+    type: Literal["message_update"] = "message_update"
+    message: AssistantMessage
+    stream_event: StreamEvent
+
+
+class MessageEnd(BaseModel):
+    type: Literal["message_end"] = "message_end"
+    message: AgentMessage
+
+
+class ToolExecutionStart(BaseModel):
+    type: Literal["tool_execution_start"] = "tool_execution_start"
+    tool_call_id: str
+    tool_name: str
+    arguments: dict[str, Any]
+
+
+class ToolExecutionUpdate(BaseModel):
+    type: Literal["tool_execution_update"] = "tool_execution_update"
+    tool_call_id: str
+    partial: ToolPartialResult
+
+
+class ToolExecutionEnd(BaseModel):
+    type: Literal["tool_execution_end"] = "tool_execution_end"
+    tool_call_id: str
+    result: ToolResultMessage
+
+
+class ErrorEvent(BaseModel):
+    type: Literal["error"] = "error"
+    error: str
+    recoverable: bool
+
+
+Event = Annotated[
+    AgentStart
+    | AgentEnd
+    | TurnStart
+    | TurnEnd
+    | MessageStart
+    | MessageUpdate
+    | MessageEnd
+    | ToolExecutionStart
+    | ToolExecutionUpdate
+    | ToolExecutionEnd
+    | ErrorEvent,
+    Field(discriminator="type"),
+]
+"""Discriminated union of agent-loop events, keyed by ``type``."""