opencomputer 0.1.0__py3-none-any.whl

opencomputer/agent/loop.py

@@ -0,0 +1,326 @@
+"""
+The agent loop — THE while loop.
+
+Kept intentionally small (target <500 lines). All the architectural ideas
+we studied condense to this:
+    1. user message arrives
+    2. loop:
+         call LLM with current messages + tool schemas
+         if response has tool_calls:
+             dispatch them in parallel (where safe), append results
+             continue
+         else:
+             break — this is the final answer
+    3. persist the conversation to SQLite
+    4. return the final message
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from dataclasses import dataclass
+
+from opencomputer.agent.compaction import CompactionEngine
+from opencomputer.agent.config import Config
+from opencomputer.agent.injection import engine as injection_engine
+from opencomputer.agent.memory import MemoryManager
+from opencomputer.agent.prompt_builder import PromptBuilder
+from opencomputer.agent.state import SessionDB
+from opencomputer.agent.step import StepOutcome
+from opencomputer.tools.registry import registry
+from plugin_sdk.core import Message, StopReason, ToolCall
+from plugin_sdk.injection import InjectionContext
+from plugin_sdk.provider_contract import BaseProvider
+from plugin_sdk.runtime_context import DEFAULT_RUNTIME_CONTEXT, RuntimeContext
+
+
+@dataclass(slots=True)
+class ConversationResult:
+    """What a full run_conversation call returns."""
+
+    final_message: Message
+    messages: list[Message]
+    session_id: str
+    iterations: int
+    input_tokens: int
+    output_tokens: int
+
+
+class AgentLoop:
+    """The single while-loop that runs the agent."""
+
+    def __init__(
+        self,
+        provider: BaseProvider,
+        config: Config,
+        db: SessionDB | None = None,
+        memory: MemoryManager | None = None,
+        prompt_builder: PromptBuilder | None = None,
+        compaction_disabled: bool = False,
+    ) -> None:
+        self.provider = provider
+        self.config = config
+        self.db = db or SessionDB(config.session.db_path)
+        self.memory = memory or MemoryManager(
+            config.memory.declarative_path, config.memory.skills_path
+        )
+        self.prompt_builder = prompt_builder or PromptBuilder()
+        self.compaction = CompactionEngine(
+            provider=provider,
+            model=config.model.model,
+            disabled=compaction_disabled,
+        )
+        self._last_input_tokens = 0
+
+    # ─── the loop ──────────────────────────────────────────────────
+
+    async def run_conversation(
+        self,
+        user_message: str,
+        session_id: str | None = None,
+        system_override: str | None = None,
+        runtime: RuntimeContext | None = None,
+        stream_callback=None,
+    ) -> ConversationResult:
+        sid = session_id or str(uuid.uuid4())
+        self._runtime = runtime or DEFAULT_RUNTIME_CONTEXT
+
+        # If this is a fresh session, create it in the DB and seed history from disk.
+        existing = self.db.get_session(sid) if session_id else None
+        if existing is None:
+            self.db.create_session(
+                session_id=sid,
+                platform="cli",
+                model=self.config.model.model,
+            )
+            messages: list[Message] = []
+        else:
+            messages = self.db.get_messages(sid)
+
+        # Build system prompt fresh every turn (cheap, keeps skill list up to date)
+        if system_override is not None:
+            base_system = system_override
+        else:
+            skills = self.memory.list_skills()
+            base_system = self.prompt_builder.build(skills=skills)
+
+        # Collect dynamic injections (plan_mode, yolo_mode, etc. from plugins)
+        inj_ctx = InjectionContext(
+            messages=tuple(messages),
+            runtime=self._runtime,
+            session_id=sid,
+        )
+        injected = injection_engine.compose(inj_ctx)
+        system = base_system + ("\n\n" + injected if injected else "")
+
+        # Append user message + persist
+        user_msg = Message(role="user", content=user_message)
+        messages.append(user_msg)
+        self.db.append_message(sid, user_msg)
+
+        total_input = 0
+        total_output = 0
+        iterations = 0
+
+        for _iter in range(self.config.loop.max_iterations):
+            iterations += 1
+
+            # Compaction check — uses REAL measured tokens from prior turn.
+            # First iteration (no prior measurement) skips the check.
+            if self._last_input_tokens > 0:
+                result = await self.compaction.maybe_run(
+                    messages, self._last_input_tokens
+                )
+                if result.did_compact:
+                    messages = result.messages
+                    # Re-collect injections with the new message list
+                    inj_ctx = InjectionContext(
+                        messages=tuple(messages),
+                        runtime=self._runtime,
+                        session_id=sid,
+                    )
+                    injected = injection_engine.compose(inj_ctx)
+                    system = base_system + ("\n\n" + injected if injected else "")
+
+            step = await self._run_one_step(
+                messages=messages, system=system, stream_callback=stream_callback
+            )
+            self._last_input_tokens = step.input_tokens
+            total_input += step.input_tokens
+            total_output += step.output_tokens
+            messages.append(step.assistant_message)
+            self.db.append_message(sid, step.assistant_message)
+
+            if not step.should_continue:
+                self.db.end_session(sid)
+                return ConversationResult(
+                    final_message=step.assistant_message,
+                    messages=messages,
+                    session_id=sid,
+                    iterations=iterations,
+                    input_tokens=total_input,
+                    output_tokens=total_output,
+                )
+
+            # Push the current runtime to DelegateTool so subagents inherit it
+            try:
+                from opencomputer.tools.delegate import DelegateTool
+
+                DelegateTool.set_runtime(self._runtime)
+            except Exception:
+                pass  # delegate tool may not be registered yet in some contexts
+
+            # Dispatch all tool calls from this step (runtime flows into hooks via sid)
+            tool_results = await self._dispatch_tool_calls(
+                step.assistant_message.tool_calls or [],
+                session_id=sid,
+            )
+            for tr_msg in tool_results:
+                messages.append(tr_msg)
+                self.db.append_message(sid, tr_msg)
+
+        # Budget exhausted
+        final = Message(
+            role="assistant",
+            content="[loop iteration budget exhausted — agent did not finish]",
+        )
+        messages.append(final)
+        self.db.append_message(sid, final)
+        self.db.end_session(sid)
+        return ConversationResult(
+            final_message=final,
+            messages=messages,
+            session_id=sid,
+            iterations=iterations,
+            input_tokens=total_input,
+            output_tokens=total_output,
+        )
+
+    # ─── one step ──────────────────────────────────────────────────
+
+    async def _run_one_step(
+        self,
+        *,
+        messages: list[Message],
+        system: str,
+        stream_callback=None,
+    ) -> StepOutcome:
+        """One LLM call + classification of the result.
+
+        If `stream_callback` is provided, stream_complete is used and each
+        text chunk is passed to the callback synchronously.
+        """
+        if stream_callback is not None:
+            final_response = None
+            async for event in self.provider.stream_complete(
+                model=self.config.model.model,
+                messages=messages,
+                system=system,
+                tools=registry.schemas(),
+                max_tokens=self.config.model.max_tokens,
+                temperature=self.config.model.temperature,
+            ):
+                if event.kind == "text_delta":
+                    stream_callback(event.text)
+                elif event.kind == "done":
+                    final_response = event.response
+            if final_response is None:
+                raise RuntimeError("stream ended without a 'done' event")
+            resp = final_response
+        else:
+            resp = await self.provider.complete(
+                model=self.config.model.model,
+                messages=messages,
+                system=system,
+                tools=registry.schemas(),
+                max_tokens=self.config.model.max_tokens,
+                temperature=self.config.model.temperature,
+            )
+
+        stop_reason_map = {
+            "end_turn": StopReason.END_TURN,
+            "tool_use": StopReason.TOOL_USE,
+            "max_tokens": StopReason.MAX_TOKENS,
+            "stop_sequence": StopReason.END_TURN,
+        }
+        stop = stop_reason_map.get(resp.stop_reason, StopReason.END_TURN)
+
+        # If the model called tools, even if the raw stop_reason was "end_turn",
+        # we need to continue so the model can process results.
+        if resp.message.tool_calls and stop == StopReason.END_TURN:
+            stop = StopReason.TOOL_USE
+
+        return StepOutcome(
+            stop_reason=stop,
+            assistant_message=resp.message,
+            tool_calls_made=len(resp.message.tool_calls or []),
+            input_tokens=resp.usage.input_tokens,
+            output_tokens=resp.usage.output_tokens,
+        )
+
+    # ─── tool dispatch ─────────────────────────────────────────────
+
+    async def _dispatch_tool_calls(
+        self, calls: list[ToolCall], session_id: str = ""
+    ) -> list[Message]:
+        """Run all tool calls — in parallel where safe — and return result Messages.
+
+        Fires PreToolUse hooks before each tool runs. If a hook blocks, the tool
+        is skipped and an error ToolResult is synthesized. Runtime context flows
+        to hooks so plan_mode_block etc. can read it.
+        """
+        if not calls:
+            return []
+
+        # Fire PreToolUse hooks first (blocking). Determine which calls are blocked.
+        from opencomputer.hooks.engine import engine as hook_engine
+        from plugin_sdk.core import ToolResult
+        from plugin_sdk.hooks import HookContext, HookEvent
+
+        blocked: dict[str, str] = {}  # call.id → block reason
+        for c in calls:
+            ctx = HookContext(
+                event=HookEvent.PRE_TOOL_USE,
+                session_id=session_id,
+                tool_call=c,
+                runtime=self._runtime,
+            )
+            decision = await hook_engine.fire_blocking(ctx)
+            if decision is not None and decision.decision == "block":
+                blocked[c.id] = decision.reason or "blocked by hook"
+
+        async def _run_one(c: ToolCall):
+            if c.id in blocked:
+                return ToolResult(
+                    tool_call_id=c.id,
+                    content=f"[blocked by PreToolUse hook: {blocked[c.id]}]",
+                    is_error=True,
+                )
+            return await registry.dispatch(c)
+
+        if self.config.loop.parallel_tools and self._all_parallel_safe(calls):
+            results = await asyncio.gather(*(_run_one(c) for c in calls))
+        else:
+            results = [await _run_one(c) for c in calls]
+
+        return [
+            Message(
+                role="tool",
+                content=r.content,
+                tool_call_id=r.tool_call_id,
+                name=next((c.name for c in calls if c.id == r.tool_call_id), None),
+            )
+            for r in results
+        ]
+
+    def _all_parallel_safe(self, calls: list[ToolCall]) -> bool:
+        """Only parallelize when every tool in the batch declared parallel_safe."""
+        for c in calls:
+            tool = registry.get(c.name)
+            if tool is None or not tool.parallel_safe:
+                return False
+        return True
+
+
+__all__ = ["AgentLoop", "ConversationResult"]

opencomputer/agent/memory.py

@@ -0,0 +1,132 @@
+"""
+Three-pillar memory manager.
+
+- Declarative: MEMORY.md + USER.md (plain markdown the user/agent edit)
+- Procedural:  ~/.opencomputer/skills/*/SKILL.md (skills folder)
+- Episodic:    SQLite + FTS5 (via SessionDB, not here)
+
+This module owns the declarative + procedural reads/writes.
+Episodic memory is queried through SessionDB in state.py.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import frontmatter
+
+
+@dataclass(frozen=True, slots=True)
+class SkillMeta:
+    """Lightweight skill metadata — from frontmatter, without loading the body."""
+
+    id: str
+    name: str
+    description: str
+    path: Path
+    version: str = "0.1.0"
+
+
+class MemoryManager:
+    """Reads declarative memory and lists procedural (skill) memory.
+
+    Skills are searched across multiple roots (kimi-cli pattern):
+      1. User skills: ~/.opencomputer/skills/   (write target for new skills)
+      2. Bundled skills: <repo>/opencomputer/skills/ (read-only, shipped defaults)
+
+    Higher-priority roots shadow lower-priority ones by skill id.
+    """
+
+    def __init__(
+        self,
+        declarative_path: Path,
+        skills_path: Path,
+        bundled_skills_paths: list[Path] | None = None,
+    ) -> None:
+        self.declarative_path = declarative_path
+        self.skills_path = skills_path
+        self.skills_path.mkdir(parents=True, exist_ok=True)
+        # Always include bundled skills shipped with core at the lowest priority
+        if bundled_skills_paths is None:
+            bundled = Path(__file__).resolve().parent.parent / "skills"
+            bundled_skills_paths = [bundled] if bundled.exists() else []
+        self.bundled_skills_paths = bundled_skills_paths
+
+    # ─── declarative ──────────────────────────────────────────────
+
+    def read_declarative(self) -> str:
+        """Return the entire MEMORY.md contents (empty string if missing)."""
+        if not self.declarative_path.exists():
+            return ""
+        return self.declarative_path.read_text(encoding="utf-8")
+
+    def append_declarative(self, text: str) -> None:
+        """Append a block of text to MEMORY.md."""
+        self.declarative_path.parent.mkdir(parents=True, exist_ok=True)
+        existing = self.read_declarative()
+        separator = "\n\n" if existing and not existing.endswith("\n\n") else ""
+        self.declarative_path.write_text(
+            existing + separator + text.strip() + "\n",
+            encoding="utf-8",
+        )
+
+    # ─── procedural (skills) ─────────────────────────────────────
+
+    def list_skills(self) -> list[SkillMeta]:
+        """Scan all skill roots for SKILL.md files. User skills shadow bundled ones."""
+        roots = [self.skills_path, *self.bundled_skills_paths]
+        seen_ids: set[str] = set()
+        out: list[SkillMeta] = []
+        for root in roots:
+            if not root.exists():
+                continue
+            for skill_dir in root.iterdir():
+                if not skill_dir.is_dir() or skill_dir.name in seen_ids:
+                    continue
+                skill_md = skill_dir / "SKILL.md"
+                if not skill_md.exists():
+                    continue
+                try:
+                    post = frontmatter.load(skill_md)
+                except Exception:
+                    continue
+                meta = post.metadata
+                seen_ids.add(skill_dir.name)
+                out.append(
+                    SkillMeta(
+                        id=skill_dir.name,
+                        name=str(meta.get("name", skill_dir.name)),
+                        description=str(meta.get("description", "")),
+                        path=skill_md,
+                        version=str(meta.get("version", "0.1.0")),
+                    )
+                )
+        return out
+
+    def load_skill_body(self, skill_id: str) -> str:
+        """Load the full text of a skill's SKILL.md (minus frontmatter)."""
+        skill_md = self.skills_path / skill_id / "SKILL.md"
+        if not skill_md.exists():
+            return ""
+        post = frontmatter.load(skill_md)
+        return post.content
+
+    def write_skill(
+        self, skill_id: str, description: str, body: str, version: str = "0.1.0"
+    ) -> Path:
+        """Create (or overwrite) a skill at ~/.opencomputer/skills/<skill_id>/SKILL.md."""
+        skill_dir = self.skills_path / skill_id
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        skill_md = skill_dir / "SKILL.md"
+        post = frontmatter.Post(
+            body,
+            name=skill_id,
+            description=description,
+            version=version,
+        )
+        skill_md.write_text(frontmatter.dumps(post), encoding="utf-8")
+        return skill_md
+
+
+__all__ = ["MemoryManager", "SkillMeta"]

opencomputer/agent/prompt_builder.py

@@ -0,0 +1,66 @@
+"""
+Prompt builder — Jinja2 templates + slot injection.
+
+Loads `base.j2` and renders it with runtime variables (cwd, user_home,
+time, available skills, etc). Keeps the prompt out of code and makes
+customization trivial — users can edit the .j2 files.
+"""
+
+from __future__ import annotations
+
+import datetime
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from opencomputer.agent.memory import SkillMeta
+
+
+@dataclass(frozen=True, slots=True)
+class PromptContext:
+    """Variables injected into prompt templates."""
+
+    cwd: str = ""
+    user_home: str = ""
+    now: str = ""
+    skills: list[SkillMeta] | None = None
+
+
+class PromptBuilder:
+    """Renders system prompts from Jinja2 templates."""
+
+    def __init__(self, templates_dir: Path | None = None) -> None:
+        if templates_dir is None:
+            templates_dir = Path(__file__).parent / "prompts"
+        self.env = Environment(
+            loader=FileSystemLoader(str(templates_dir)),
+            autoescape=select_autoescape(disabled_extensions=("j2",)),
+            keep_trailing_newline=True,
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+    def build(
+        self,
+        *,
+        skills: list[SkillMeta] | None = None,
+        template: str = "base.j2",
+    ) -> str:
+        ctx = PromptContext(
+            cwd=os.getcwd(),
+            user_home=str(Path.home()),
+            now=datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            skills=skills or [],
+        )
+        tpl = self.env.get_template(template)
+        return tpl.render(
+            cwd=ctx.cwd,
+            user_home=ctx.user_home,
+            now=ctx.now,
+            skills=ctx.skills,
+        )
+
+
+__all__ = ["PromptBuilder", "PromptContext"]

opencomputer/agent/prompts/base.j2

@@ -0,0 +1,23 @@
+You are OpenComputer — a personal AI agent running on {{ user_home }}.
+
+Current working directory: {{ cwd }}
+Current time: {{ now }}
+
+You have tools available. Use them to accomplish what the user asks.
+
+{% if skills -%}
+## Skills available
+
+{% for skill in skills -%}
+- **{{ skill.name }}** — {{ skill.description }}
+{% endfor %}
+
+When one of these skills matches the user's task, follow its guidance.
+{%- endif %}
+
+## Working rules
+
+- When the user asks you to do something, USE YOUR TOOLS to actually do it. Don't describe what you would do — do it.
+- Be concise in your responses. The user prefers action over explanation.
+- When a complex task is complete, consider saving the approach as a skill
+  using the skill_manage tool, so it can be reused next time.