pico-cli-core 0.1.1__tar.gz

pico_cli_core-0.1.1/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

pico_cli_core-0.1.1/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.5
+Name: pico-cli-core
+Version: 0.1.1
+Summary: Agent loop and session tree.
+Project-URL: Homepage, https://github.com/Arya-Ojha/PicoCLI_Learn
+Project-URL: Repository, https://github.com/Arya-Ojha/PicoCLI_Learn
+Project-URL: Issues, https://github.com/Arya-Ojha/PicoCLI_Learn/issues
+Author-email: Arya-Ojha <aryaojha195@gmail.com>
+License-Expression: MIT
+Keywords: agent-loop,ai-agent,llm-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pico-cli-ai
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# pico-cli-core
+
+The agent loop (explicit finite-state machine) and the append-only, tree-based session model for `pico-cli`: nine hardcoded core tools (`read`, `write`, `edit`, `grep`, `fetch`, `websearch`, `bash`, `todo`, `task`), todo tracking, sub-agents, and compaction.
+
+See the [pico-cli README](https://github.com/Arya-Ojha/PicoCLI_Learn#readme) for the full picture.

pico_cli_core-0.1.1/README.md

@@ -0,0 +1,5 @@
+# pico-cli-core
+
+The agent loop (explicit finite-state machine) and the append-only, tree-based session model for `pico-cli`: nine hardcoded core tools (`read`, `write`, `edit`, `grep`, `fetch`, `websearch`, `bash`, `todo`, `task`), todo tracking, sub-agents, and compaction.
+
+See the [pico-cli README](https://github.com/Arya-Ojha/PicoCLI_Learn#readme) for the full picture.

pico_cli_core-0.1.1/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "pico-cli-core"
+version = "0.1.1"
+description = "Agent loop and session tree."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Arya-Ojha", email = "aryaojha195@gmail.com" }]
+keywords = ["ai-agent", "agent-loop", "llm-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.12"
+dependencies = ["pico-cli-ai", "pydantic>=2", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/Arya-Ojha/PicoCLI_Learn"
+Repository = "https://github.com/Arya-Ojha/PicoCLI_Learn"
+Issues = "https://github.com/Arya-Ojha/PicoCLI_Learn/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pico_core"]
+
+[tool.uv.sources]
+pico-cli-ai = { workspace = true }

pico_cli_core-0.1.1/src/pico_core/__init__.py

@@ -0,0 +1,71 @@
+"""pico_core: the agent loop (state machine) and the session tree."""
+
+from .fsm import AgentLoop, AgentState, LoopEvent, RunResult
+from .session import (
+    AssistantBlock,
+    AssistantPayload,
+    CompactionSummaryPayload,
+    Node,
+    Session,
+    ToolRequestPayload,
+    ToolResultPayload,
+    UserPayload,
+)
+from .subagents import (
+    DEFAULT_CHILD_TOOLS,
+    MAX_DEPTH,
+    ChildFactory,
+    ChildSpec,
+    SpawnTool,
+)
+from .todos import TodoItem, TodoList, TodoTool, format_todos
+from .trace import TraceRow, assemble_trace_rows
+from .tools import (
+    BashTool,
+    EditTool,
+    FetchTool,
+    GrepTool,
+    ReadTool,
+    Tool,
+    ToolOutcome,
+    ToolRegistry,
+    WebSearchTool,
+    WriteTool,
+)
+
+__all__ = [
+    "AgentLoop",
+    "AgentState",
+    "LoopEvent",
+    "RunResult",
+    "AssistantBlock",
+    "AssistantPayload",
+    "CompactionSummaryPayload",
+    "Node",
+    "Session",
+    "ToolRequestPayload",
+    "ToolResultPayload",
+    "UserPayload",
+    "BashTool",
+    "EditTool",
+    "FetchTool",
+    "GrepTool",
+    "ReadTool",
+    "Tool",
+    "ToolOutcome",
+    "ToolRegistry",
+    "WebSearchTool",
+    "WriteTool",
+    "DEFAULT_CHILD_TOOLS",
+    "MAX_DEPTH",
+    "ChildFactory",
+    "ChildSpec",
+    "SpawnTool",
+    "TodoItem",
+    "TodoList",
+    "TodoTool",
+    "format_todos",
+    "TraceRow",
+    "assemble_trace_rows",
+]
+

pico_cli_core-0.1.1/src/pico_core/fsm.py

@@ -0,0 +1,491 @@
+"""The explicit finite-state-machine agent loop.
+
+States::
+
+    idle → streaming ⇄ tool_executing → done
+             ↓
+          compacting          (triggered by token threshold)
+    error                     (reachable from any state)
+
+Yolo mode means there is no approval/confirmation state.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncIterator, Callable
+from enum import Enum
+from typing import Literal, Protocol
+
+from pydantic import BaseModel
+
+from pico_ai.provider import Provider
+from pico_ai.types import AICallRequest, Message, StreamEvent, ToolCall, Usage
+
+from .session import (
+    AssistantBlock,
+    AssistantPayload,
+    CompactionSummaryPayload,
+    Node,
+    Session,
+    ToolRequestPayload,
+    ToolResultPayload,
+    UserPayload,
+)
+from .todos import TodoItem, TodoTool
+from .tools import ToolRegistry
+
+
+class AgentState(str, Enum):
+    IDLE = "idle"
+    STREAMING = "streaming"
+    TOOL_EXECUTING = "tool_executing"
+    COMPACTING = "compacting"
+    DONE = "done"
+    ERROR = "error"
+
+
+class LoopEvent(BaseModel):
+    """A single observable event emitted by the agent loop."""
+
+    kind: Literal[
+        "text", "thinking", "tool_call", "tool_request", "tool_result", "state", "usage"
+    ]
+    text: str = ""
+    thinking: str = ""
+    tool_call: ToolCall | None = None
+    tool_request: ToolRequestPayload | None = None
+    tool_result: ToolResultPayload | None = None
+    state: AgentState | None = None
+    usage: Usage | None = None
+
+
+class RunResult(BaseModel):
+    """The outcome of a completed run."""
+
+    text: str
+    state: AgentState
+    session: Session
+    error: str | None = None
+    truncated: bool = False
+
+
+class HookSink(Protocol):
+    """Lifecycle hooks the loop can fire (implemented by the SDK)."""
+
+    async def on_session_start(self, session: Session) -> None: ...
+    async def tool_before(self, name: str, arguments: dict) -> None: ...
+    async def tool_after(
+        self, name: str, arguments: dict, result: ToolResultPayload
+    ) -> None: ...
+
+
+Summarizer = Callable[[list[Node], str], AsyncIterator[StreamEvent]]
+
+
+# A run only ends once every todo is completed. When the model stops with
+# unfinished todos, the loop nudges it back in instead of finishing — capped
+# so a stuck model still terminates instead of burning calls forever.
+MAX_TODO_NUDGES = 5
+
+
+async def _collect_text(stream: AsyncIterator[StreamEvent]) -> str:
+    parts: list[str] = []
+    async for event in stream:
+        if event.kind == "text":
+            parts.append(event.text)
+    return "".join(parts)
+
+
+class AgentLoop:
+    """Drives a session through the FSM using a provider and a tool registry."""
+
+    def __init__(
+        self,
+        provider: Provider,
+        session: Session,
+        tools: ToolRegistry,
+        *,
+        system_prompt: str = "",
+        model: str = "",
+        context_window: int = 128_000,
+        reserve_tokens: int = 16_384,
+        summarizer: Summarizer | None = None,
+        hooks: HookSink | None = None,
+        allowed_tools: list[str] | None = None,
+    ) -> None:
+        self.provider = provider
+        self.session = session
+        self.tools = tools
+        self.system_prompt = system_prompt
+        self.model = model
+        self.context_window = context_window
+        self.reserve_tokens = reserve_tokens
+        self._summarizer = summarizer or self._default_summarizer
+        self._hooks = hooks
+        # Permission gating (ADR-0003): None allows every registered tool.
+        self.allowed_tools = list(allowed_tools) if allowed_tools is not None else None
+        self.state = AgentState.IDLE
+        self._started = False
+        self._todo_nudges = 0
+        #: True when the last ``stream()`` stopped at ``max_turns``.
+        self.last_truncated = False
+
+    # -- public -------------------------------------------------------------
+
+    async def run(self, prompt: str, *, max_turns: int | None = None) -> RunResult:
+        """Run the full loop and return the final result."""
+        text_parts: list[str] = []
+        try:
+            async for event in self.stream(prompt, max_turns=max_turns):
+                if event.kind == "text":
+                    text_parts.append(event.text)
+        except Exception as exc:  # noqa: BLE001 - surface as error state
+            self.state = AgentState.ERROR
+            return RunResult(
+                text="".join(text_parts),
+                state=AgentState.ERROR,
+                session=self.session,
+                error=str(exc),
+            )
+        return RunResult(
+            text="".join(text_parts),
+            state=self.state,
+            session=self.session,
+            truncated=self.last_truncated,
+        )
+
+    async def stream(
+        self, prompt: str, *, max_turns: int | None = None
+    ) -> AsyncIterator[LoopEvent]:
+        """Run the loop, yielding observable events as they happen."""
+        self._set_state(AgentState.IDLE)
+        self.last_truncated = False
+        yield self._state_event()
+        if self._hooks is not None and not self._started:
+            await self._hooks.on_session_start(self.session)
+            self._started = True
+
+        self.session.append(
+            self.session.active_leaf_id, UserPayload(content=prompt)
+        )
+
+        turns = 0
+        while True:
+            if self._needs_compaction():
+                async for event in self._compact():
+                    yield event
+
+            self._set_state(AgentState.STREAMING)
+            yield self._state_event()
+            turns += 1
+            if max_turns is not None and turns > max_turns:
+                # Turn cap hit (sub-agent bounding): stop cleanly with
+                # whatever text was produced so far.
+                self.last_truncated = True
+                self._set_state(AgentState.DONE)
+                yield self._state_event()
+                return
+
+            request = self._build_request()
+            blocks: list[AssistantBlock] = []
+            tool_calls: list[ToolCall] = []
+            usage: Usage | None = None
+
+            # Trace timing (ADR-0006): the assistant node carries the
+            # provider-stream wall-time. The finally-append also covers
+            # interrupted streams (partial blocks + measured duration);
+            # the exception still propagates to the caller.
+            stream_start = time.perf_counter()
+            try:
+                async for stream_event in self.provider.stream(request):
+                    if stream_event.kind == "text":
+                        blocks.append(AssistantBlock(kind="text", text=stream_event.text))
+                        yield LoopEvent(kind="text", text=stream_event.text)
+                    elif stream_event.kind == "thinking":
+                        blocks.append(AssistantBlock(kind="thinking", thinking=stream_event.thinking))
+                        yield LoopEvent(kind="thinking", thinking=stream_event.thinking)
+                    elif stream_event.kind == "tool_call" and stream_event.tool_call is not None:
+                        tool_calls.append(stream_event.tool_call)
+                        yield LoopEvent(kind="tool_call", tool_call=stream_event.tool_call)
+                    elif stream_event.kind == "usage" and stream_event.usage is not None:
+                        usage = stream_event.usage
+            finally:
+                stream_ms = (time.perf_counter() - stream_start) * 1000.0
+                self.session.append(
+                    self.session.active_leaf_id,
+                    AssistantPayload(blocks=blocks, usage=usage, duration_ms=stream_ms),
+                )
+            if usage is not None:
+                yield LoopEvent(kind="usage", usage=usage)
+
+            if not tool_calls:
+                unfinished = self._unfinished_todos()
+                if unfinished and self._todo_nudges < MAX_TODO_NUDGES:
+                    self._todo_nudges += 1
+                    self.session.append(
+                        self.session.active_leaf_id,
+                        UserPayload(content=_todo_nudge(unfinished)),
+                    )
+                    continue
+                self._todo_nudges = 0
+                if not unfinished:
+                    self._clear_finished_todos()
+                self._set_state(AgentState.DONE)
+                yield self._state_event()
+                return
+
+            self._set_state(AgentState.TOOL_EXECUTING)
+            yield self._state_event()
+
+            if any(c.name == "todo" for c in tool_calls):
+                # Progress on the list — reset the stuck-model counter.
+                self._todo_nudges = 0
+
+            if tool_calls and all(c.name == "task" for c in tool_calls):
+                # A turn of pure delegation fans out concurrently; requests
+                # are recorded first, then executions gather, then results
+                # are appended in call order so the tree stays deterministic.
+                for tool_call in tool_calls:
+                    request_payload = ToolRequestPayload(tool_call=tool_call)
+                    self.session.append(self.session.active_leaf_id, request_payload)
+                    yield LoopEvent(kind="tool_request", tool_request=request_payload)
+                results = await asyncio.gather(
+                    *(self._execute_tool(tool_call) for tool_call in tool_calls)
+                )
+                for result in results:
+                    self.session.append(self.session.active_leaf_id, result)
+                    yield LoopEvent(kind="tool_result", tool_result=result)
+                continue
+
+            for tool_call in tool_calls:
+                request_payload = ToolRequestPayload(tool_call=tool_call)
+                self.session.append(self.session.active_leaf_id, request_payload)
+                yield LoopEvent(kind="tool_request", tool_request=request_payload)
+                result = await self._execute_tool(tool_call)
+                self.session.append(self.session.active_leaf_id, result)
+                yield LoopEvent(kind="tool_result", tool_result=result)
+
+    # -- context assembly ---------------------------------------------------
+
+    def _build_request(self) -> AICallRequest:
+        messages: list[Message] = []
+        last_assistant = -1
+        for node in self.session.active_branch():
+            payload = node.payload
+            if isinstance(payload, CompactionSummaryPayload):
+                # A compaction summary replaces everything before it.
+                messages = [
+                    Message(role="user", content=f"[compacted context]\n{payload.summary}")
+                ]
+                last_assistant = -1
+            elif isinstance(payload, UserPayload):
+                messages.append(Message(role="user", content=payload.content))
+                last_assistant = -1
+            elif isinstance(payload, AssistantPayload):
+                messages.append(Message(role="assistant", content=payload.text))
+                last_assistant = len(messages) - 1
+            elif isinstance(payload, ToolRequestPayload):
+                if last_assistant >= 0:
+                    messages[last_assistant].tool_calls.append(payload.tool_call)
+            elif isinstance(payload, ToolResultPayload):
+                messages.append(
+                    Message(
+                        role="tool",
+                        tool_call_id=payload.tool_call_id,
+                        name=payload.name,
+                        content=payload.content,
+                    )
+                )
+                # Note: do NOT reset last_assistant here — a single assistant
+                # turn can make several tool calls, and every tool_request in
+                # that turn must attach to the same assistant message.
+        return AICallRequest(
+            system=self.system_prompt,
+            messages=messages,
+            tools=self.tools.definitions(),
+            model=self.model,
+        )
+
+    def _context_text(self) -> str:
+        parts = [self.system_prompt]
+        for node in self.session.active_branch():
+            payload = node.payload
+            if isinstance(payload, CompactionSummaryPayload):
+                # A summary replaces everything before it.
+                parts = [self.system_prompt, payload.summary]
+            elif isinstance(payload, UserPayload):
+                parts.append(payload.content)
+            elif isinstance(payload, AssistantPayload):
+                parts.append(payload.text)
+            elif isinstance(payload, ToolResultPayload):
+                parts.append(payload.content)
+        return "\n".join(parts)
+
+    def estimate_tokens(self) -> int:
+        """Return the current estimated token count for the context."""
+        return self._estimate_tokens()
+
+    def _estimate_tokens(self) -> int:
+        # Rough heuristic: ~4 characters per token.
+        return len(self._context_text()) // 4
+
+    # -- compaction ---------------------------------------------------------
+
+    def _needs_compaction(self) -> bool:
+        return self._estimate_tokens() > self.context_window - self.reserve_tokens
+
+    def _split_for_compaction(
+        self, branch: list[Node], keep_turns: int
+    ) -> tuple[list[Node], list[Node]]:
+        """Split the branch into (to_summarize, to_keep).
+
+        The ``keep_turns`` most recent user turns — and everything after them —
+        form the recent window; everything before them is summarised.
+        """
+        user_indices = [
+            i for i, n in enumerate(branch) if isinstance(n.payload, UserPayload)
+        ]
+        if len(user_indices) <= keep_turns:
+            return [], branch
+        cutoff = user_indices[-keep_turns]
+        return branch[:cutoff], branch[cutoff:]
+
+    async def _compact(
+        self, instructions: str = "", keep_turns: int = 1
+    ) -> AsyncIterator[LoopEvent]:
+        self._set_state(AgentState.COMPACTING)
+        yield self._state_event()
+        branch = self.session.active_branch()
+        to_summarize, to_keep = self._split_for_compaction(branch, keep_turns)
+        if not to_summarize:
+            return
+        summary = await _collect_text(self._summarizer(to_summarize, instructions))
+        self.session.append(
+            self.session.active_leaf_id, CompactionSummaryPayload(summary=summary)
+        )
+        # Re-append the kept recent window after the summary (append-only).
+        for node in to_keep:
+            self.session.append(self.session.active_leaf_id, node.payload)
+
+    async def compact(self, instructions: str = "") -> None:
+        """Manually trigger compaction with optional steering instructions."""
+        async for _ in self._compact(instructions):
+            pass
+
+    async def _default_summarizer(
+        self, nodes: list[Node], instructions: str
+    ) -> AsyncIterator[StreamEvent]:
+        content = "\n".join(_render_node(n) for n in nodes)
+        request = AICallRequest(
+            system="Summarize the following conversation, preserving all key facts, "
+            "decisions, and outstanding tasks.",
+            messages=[Message(role="user", content=content + "\n" + instructions)],
+            model=self.model,
+        )
+        async for event in self.provider.stream(request):
+            yield event
+
+    # -- tool execution -----------------------------------------------------
+
+    def _unfinished_todos(self) -> list[TodoItem]:
+        """Return every todo that is not completed (empty when no tracker)."""
+        tool = self.tools.get("todo")
+        if not isinstance(tool, TodoTool):
+            return []
+        return [i for i in tool.todos.all() if i.status != "completed"]
+
+    def _clear_finished_todos(self) -> None:
+        """Drop the todo list once a run ends with everything completed.
+
+        Only fires when nothing is unfinished, so a run stopped by the
+        nudge cap keeps its open todos visible instead of losing them.
+        """
+        tool = self.tools.get("todo")
+        if isinstance(tool, TodoTool) and len(tool.todos) > 0:
+            tool.todos.clear_completed()
+
+    async def _execute_tool(self, tool_call: ToolCall) -> ToolResultPayload:
+        # Every attempted call fires pre_tool_use first, so hook observers see
+        # a complete attempt log; every terminal path below fires tool_after
+        # (which fans out to post_tool_use and, on error, post_tool_failure).
+        if self._hooks is not None:
+            await self._hooks.tool_before(tool_call.name, tool_call.arguments)
+        if self.allowed_tools is not None and tool_call.name not in self.allowed_tools:
+            result = ToolResultPayload(
+                tool_call_id=tool_call.id,
+                name=tool_call.name,
+                content=f"error: tool not allowed: {tool_call.name}",
+                is_error=True,
+            )
+            if self._hooks is not None:
+                await self._hooks.tool_after(
+                    tool_call.name, tool_call.arguments, result
+                )
+            return result
+        tool = self.tools.get(tool_call.name)
+        if tool is None:
+            result = ToolResultPayload(
+                tool_call_id=tool_call.id,
+                name=tool_call.name,
+                content=f"error: unknown tool: {tool_call.name}",
+                is_error=True,
+            )
+            if self._hooks is not None:
+                await self._hooks.tool_after(
+                    tool_call.name, tool_call.arguments, result
+                )
+            return result
+        try:
+            outcome = await tool.run(tool_call.arguments)
+        except Exception as exc:  # noqa: BLE001 - surface as a result
+            result = ToolResultPayload(
+                tool_call_id=tool_call.id,
+                name=tool_call.name,
+                content=f"error: {exc}",
+                is_error=True,
+            )
+        else:
+            result = ToolResultPayload(
+                tool_call_id=tool_call.id,
+                name=tool_call.name,
+                content=outcome.content,
+                is_error=outcome.is_error,
+            )
+        if self._hooks is not None:
+            await self._hooks.tool_after(tool_call.name, tool_call.arguments, result)
+        return result
+
+    # -- helpers ------------------------------------------------------------
+
+    def _set_state(self, state: AgentState) -> None:
+        self.state = state
+
+    def _state_event(self) -> LoopEvent:
+        return LoopEvent(kind="state", state=self.state)
+
+
+def _todo_nudge(unfinished: list[TodoItem]) -> str:
+    """Build the keep-going message appended when the model stops early."""
+    items = "\n".join(f"[{t.id}] {t.status} — {t.text}" for t in unfinished)
+    return (
+        f"[todos] {len(unfinished)} unfinished todo(s) — do not stop yet. "
+        "Keep working, updating todos as you go, until every todo is completed:\n"
+        f"{items}"
+    )
+
+
+def _render_node(node: Node) -> str:
+    payload = node.payload
+    if isinstance(payload, UserPayload):
+        return f"user: {payload.content}"
+    if isinstance(payload, AssistantPayload):
+        return f"assistant: {payload.text}"
+    if isinstance(payload, ToolRequestPayload):
+        return f"tool request: {payload.tool_call.name} {payload.tool_call.arguments}"
+    if isinstance(payload, ToolResultPayload):
+        return f"tool result: {payload.content}"
+    if isinstance(payload, CompactionSummaryPayload):
+        return f"summary: {payload.summary}"
+    return ""

pico_cli_core-0.1.1/src/pico_core/py.typed

@@ -0,0 +1 @@
+��