opencomputer 0.1.0__py3-none-any.whl

opencomputer/tools/read.py

@@ -0,0 +1,81 @@
+"""Read tool — read the contents of a file."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from plugin_sdk.core import ToolCall, ToolResult
+from plugin_sdk.tool_contract import BaseTool, ToolSchema
+
+
+class ReadTool(BaseTool):
+    parallel_safe = True
+
+    @property
+    def schema(self) -> ToolSchema:
+        return ToolSchema(
+            name="Read",
+            description="Read the contents of a file from disk. Returns the text, "
+            "prefixed with line numbers. Supports optional offset and limit "
+            "for reading slices of large files.",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "file_path": {
+                        "type": "string",
+                        "description": "Absolute path to the file to read.",
+                    },
+                    "offset": {
+                        "type": "integer",
+                        "description": "Line number to start reading from (1-indexed).",
+                        "minimum": 1,
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum number of lines to read.",
+                        "minimum": 1,
+                    },
+                },
+                "required": ["file_path"],
+            },
+        )
+
+    async def execute(self, call: ToolCall) -> ToolResult:
+        args = call.arguments
+        path = Path(args.get("file_path", ""))
+        if not path.is_absolute():
+            return ToolResult(
+                tool_call_id=call.id,
+                content=f"Error: file_path must be absolute, got: {path}",
+                is_error=True,
+            )
+        if not path.exists():
+            return ToolResult(
+                tool_call_id=call.id,
+                content=f"Error: file does not exist: {path}",
+                is_error=True,
+            )
+        if not path.is_file():
+            return ToolResult(
+                tool_call_id=call.id,
+                content=f"Error: path is not a file: {path}",
+                is_error=True,
+            )
+
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except Exception as e:
+            return ToolResult(
+                tool_call_id=call.id,
+                content=f"Error reading {path}: {type(e).__name__}: {e}",
+                is_error=True,
+            )
+
+        lines = text.splitlines()
+        offset = max(1, int(args.get("offset", 1)))
+        limit = int(args.get("limit", 2000))
+        start_idx = offset - 1
+        end_idx = start_idx + limit
+        slice_ = lines[start_idx:end_idx]
+        numbered = "\n".join(f"{start_idx + i + 1:>6}\t{ln}" for i, ln in enumerate(slice_))
+        return ToolResult(tool_call_id=call.id, content=numbered)

opencomputer/tools/registry.py

@@ -0,0 +1,69 @@
+"""
+Tool registry — a dict + dispatch.
+
+Inspired by hermes's ToolEntry pattern. A singleton registry holds
+ToolEntries; tools register themselves via `@register_tool`. The
+agent loop asks the registry for all schemas and dispatches calls.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from plugin_sdk.core import ToolCall, ToolResult
+from plugin_sdk.tool_contract import BaseTool, ToolSchema
+
+
+class ToolRegistry:
+    """Singleton registry. Import from elsewhere as `from opencomputer.tools.registry import registry`."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, BaseTool] = {}
+
+    def register(self, tool: BaseTool) -> None:
+        name = tool.schema.name
+        if name in self._tools:
+            raise ValueError(f"Tool '{name}' is already registered")
+        self._tools[name] = tool
+
+    def unregister(self, name: str) -> None:
+        self._tools.pop(name, None)
+
+    def get(self, name: str) -> BaseTool | None:
+        return self._tools.get(name)
+
+    def schemas(self) -> list[ToolSchema]:
+        return [t.schema for t in self._tools.values()]
+
+    def names(self) -> Iterable[str]:
+        return self._tools.keys()
+
+    async def dispatch(self, call: ToolCall) -> ToolResult:
+        """Dispatch a tool call to its handler. Never raises — always returns a ToolResult."""
+        tool = self._tools.get(call.name)
+        if tool is None:
+            return ToolResult(
+                tool_call_id=call.id,
+                content=f"Error: tool '{call.name}' not found",
+                is_error=True,
+            )
+        try:
+            return await tool.execute(call)
+        except Exception as e:  # defensive — tool.execute should handle its own errors
+            return ToolResult(
+                tool_call_id=call.id,
+                content=f"Error: {type(e).__name__}: {e}",
+                is_error=True,
+            )
+
+
+registry = ToolRegistry()
+
+
+def register_tool(tool: BaseTool) -> BaseTool:
+    """Convenience: register and return the tool (so it can be used as a module-level call)."""
+    registry.register(tool)
+    return tool
+
+
+__all__ = ["ToolRegistry", "registry", "register_tool"]

opencomputer/tools/skill_manage.py

@@ -0,0 +1,265 @@
+"""
+skill_manage — the self-improvement tool.
+
+The agent calls this after completing complex tasks to save the approach
+as a reusable skill. On the next relevant conversation, the skill's
+description auto-activates and its body enters the system prompt.
+
+Inspired by hermes's tools/skill_manager_tool.py. Trimmed: only the
+actions we actually need (create/edit/patch/delete/view/list).
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import frontmatter
+
+from opencomputer.agent.config import default_config
+from plugin_sdk.core import ToolCall, ToolResult
+from plugin_sdk.tool_contract import BaseTool, ToolSchema
+
+_VALID_ID = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+
+def _skills_root() -> Path:
+    return default_config().memory.skills_path
+
+
+def _skill_dir(skill_id: str) -> Path:
+    return _skills_root() / skill_id
+
+
+def _validate_id(skill_id: str) -> str | None:
+    if not skill_id:
+        return "Error: skill id is required"
+    if not _VALID_ID.match(skill_id):
+        return f"Error: skill id '{skill_id}' must be kebab-case (lowercase, hyphens only)"
+    return None
+
+
+def _validate_frontmatter(body: str) -> str | None:
+    if not body.strip():
+        return "Error: body is empty"
+    try:
+        post = frontmatter.loads(body)
+    except Exception as e:  # noqa: BLE001
+        return f"Error parsing frontmatter: {e}"
+    meta = post.metadata
+    if "name" not in meta:
+        return "Error: frontmatter must include 'name'"
+    if "description" not in meta:
+        return "Error: frontmatter must include 'description'"
+    if not str(meta.get("description", "")).strip():
+        return "Error: description cannot be empty"
+    return None
+
+
+class SkillManageTool(BaseTool):
+    parallel_safe = False  # writes to disk
+
+    @property
+    def schema(self) -> ToolSchema:
+        return ToolSchema(
+            name="skill_manage",
+            description=(
+                "Manage skills (procedural memory). Call this AFTER completing a complex task "
+                "(5+ tool calls, tricky error, non-trivial workflow) to save the approach as a "
+                "reusable skill. Skills are auto-activated on relevant future queries.\n\n"
+                "Also use to fix outdated/wrong skills — patch them immediately when you "
+                "notice something is off.\n\n"
+                "Actions:\n"
+                "  create — make a new skill with full SKILL.md content (frontmatter + body)\n"
+                "  edit   — fully rewrite an existing skill\n"
+                "  patch  — targeted find/replace within an existing skill\n"
+                "  delete — remove a skill\n"
+                "  view   — read a skill's contents\n"
+                "  list   — list all installed skills"
+            ),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "action": {
+                        "type": "string",
+                        "enum": ["create", "edit", "patch", "delete", "view", "list"],
+                        "description": "What to do",
+                    },
+                    "name": {
+                        "type": "string",
+                        "description": "Skill id (kebab-case). Not required for list.",
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": (
+                            "Full SKILL.md content for create/edit (must include frontmatter "
+                            "with name + description)."
+                        ),
+                    },
+                    "find": {
+                        "type": "string",
+                        "description": "For patch action: exact text to find.",
+                    },
+                    "replace": {
+                        "type": "string",
+                        "description": "For patch action: replacement text.",
+                    },
+                },
+                "required": ["action"],
+            },
+        )
+
+    async def execute(self, call: ToolCall) -> ToolResult:
+        args = call.arguments
+        action = args.get("action", "").lower()
+        name = args.get("name", "")
+
+        if action == "list":
+            return self._list(call.id)
+        if action == "view":
+            return self._view(call.id, name)
+        if action == "create":
+            return self._create(call.id, name, args.get("content", ""))
+        if action == "edit":
+            return self._edit(call.id, name, args.get("content", ""))
+        if action == "patch":
+            return self._patch(
+                call.id, name, args.get("find", ""), args.get("replace", "")
+            )
+        if action == "delete":
+            return self._delete(call.id, name)
+        return ToolResult(
+            tool_call_id=call.id,
+            content=f"Error: unknown action '{action}'",
+            is_error=True,
+        )
+
+    # ─── actions ──────────────────────────────────────────────────
+
+    def _list(self, call_id: str) -> ToolResult:
+        root = _skills_root()
+        if not root.exists():
+            return ToolResult(tool_call_id=call_id, content="no skills installed")
+        lines: list[str] = []
+        for d in sorted(root.iterdir()):
+            if not d.is_dir():
+                continue
+            skill_md = d / "SKILL.md"
+            if not skill_md.exists():
+                continue
+            try:
+                post = frontmatter.load(skill_md)
+                desc = post.metadata.get("description", "")
+            except Exception:
+                desc = "[failed to parse]"
+            lines.append(f"- {d.name}: {desc}")
+        return ToolResult(
+            tool_call_id=call_id,
+            content="\n".join(lines) or "no skills installed",
+        )
+
+    def _view(self, call_id: str, name: str) -> ToolResult:
+        if err := _validate_id(name):
+            return ToolResult(tool_call_id=call_id, content=err, is_error=True)
+        skill_md = _skill_dir(name) / "SKILL.md"
+        if not skill_md.exists():
+            return ToolResult(
+                tool_call_id=call_id,
+                content=f"Error: skill '{name}' not found",
+                is_error=True,
+            )
+        return ToolResult(
+            tool_call_id=call_id, content=skill_md.read_text(encoding="utf-8")
+        )
+
+    def _create(self, call_id: str, name: str, content: str) -> ToolResult:
+        if err := _validate_id(name):
+            return ToolResult(tool_call_id=call_id, content=err, is_error=True)
+        if err := _validate_frontmatter(content):
+            return ToolResult(tool_call_id=call_id, content=err, is_error=True)
+        skill_dir = _skill_dir(name)
+        if skill_dir.exists():
+            return ToolResult(
+                tool_call_id=call_id,
+                content=f"Error: skill '{name}' already exists — use action='edit' or 'patch'",
+                is_error=True,
+            )
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+        return ToolResult(
+            tool_call_id=call_id,
+            content=f"Created skill '{name}' at {skill_dir}",
+        )
+
+    def _edit(self, call_id: str, name: str, content: str) -> ToolResult:
+        if err := _validate_id(name):
+            return ToolResult(tool_call_id=call_id, content=err, is_error=True)
+        if err := _validate_frontmatter(content):
+            return ToolResult(tool_call_id=call_id, content=err, is_error=True)
+        skill_md = _skill_dir(name) / "SKILL.md"
+        if not skill_md.exists():
+            return ToolResult(
+                tool_call_id=call_id,
+                content=f"Error: skill '{name}' not found — use action='create' to add it",
+                is_error=True,
+            )
+        skill_md.write_text(content, encoding="utf-8")
+        return ToolResult(
+            tool_call_id=call_id, content=f"Updated skill '{name}'"
+        )
+
+    def _patch(self, call_id: str, name: str, find: str, replace: str) -> ToolResult:
+        if err := _validate_id(name):
+            return ToolResult(tool_call_id=call_id, content=err, is_error=True)
+        if not find:
+            return ToolResult(
+                tool_call_id=call_id,
+                content="Error: patch requires 'find' string",
+                is_error=True,
+            )
+        skill_md = _skill_dir(name) / "SKILL.md"
+        if not skill_md.exists():
+            return ToolResult(
+                tool_call_id=call_id,
+                content=f"Error: skill '{name}' not found",
+                is_error=True,
+            )
+        text = skill_md.read_text(encoding="utf-8")
+        if find not in text:
+            return ToolResult(
+                tool_call_id=call_id,
+                content=f"Error: 'find' string not present in skill '{name}'",
+                is_error=True,
+            )
+        if text.count(find) > 1:
+            return ToolResult(
+                tool_call_id=call_id,
+                content=(
+                    f"Error: 'find' string appears {text.count(find)} times in skill "
+                    f"'{name}' — be more specific"
+                ),
+                is_error=True,
+            )
+        new_text = text.replace(find, replace)
+        skill_md.write_text(new_text, encoding="utf-8")
+        return ToolResult(
+            tool_call_id=call_id, content=f"Patched skill '{name}' (1 replacement)"
+        )
+
+    def _delete(self, call_id: str, name: str) -> ToolResult:
+        if err := _validate_id(name):
+            return ToolResult(tool_call_id=call_id, content=err, is_error=True)
+        skill_dir = _skill_dir(name)
+        if not skill_dir.exists():
+            return ToolResult(
+                tool_call_id=call_id,
+                content=f"Error: skill '{name}' not found",
+                is_error=True,
+            )
+        import shutil
+
+        shutil.rmtree(skill_dir)
+        return ToolResult(tool_call_id=call_id, content=f"Deleted skill '{name}'")
+
+
+__all__ = ["SkillManageTool"]

opencomputer/tools/write.py

@@ -0,0 +1,58 @@
+"""Write tool — write content to a file, creating parent dirs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from plugin_sdk.core import ToolCall, ToolResult
+from plugin_sdk.tool_contract import BaseTool, ToolSchema
+
+
+class WriteTool(BaseTool):
+    parallel_safe = False  # writes to same path could race
+
+    @property
+    def schema(self) -> ToolSchema:
+        return ToolSchema(
+            name="Write",
+            description="Write content to a file. Overwrites the file if it exists. "
+            "Creates parent directories as needed. file_path must be absolute.",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "file_path": {
+                        "type": "string",
+                        "description": "Absolute path to the file to write.",
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "Full contents to write.",
+                    },
+                },
+                "required": ["file_path", "content"],
+            },
+        )
+
+    async def execute(self, call: ToolCall) -> ToolResult:
+        args = call.arguments
+        path = Path(args.get("file_path", ""))
+        content = args.get("content", "")
+        if not path.is_absolute():
+            return ToolResult(
+                tool_call_id=call.id,
+                content=f"Error: file_path must be absolute, got: {path}",
+                is_error=True,
+            )
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+        except Exception as e:
+            return ToolResult(
+                tool_call_id=call.id,
+                content=f"Error writing {path}: {type(e).__name__}: {e}",
+                is_error=True,
+            )
+        return ToolResult(
+            tool_call_id=call.id,
+            content=f"Wrote {len(content)} bytes to {path}",
+        )

opencomputer-0.1.0.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: opencomputer
+Version: 0.1.0
+Summary: Personal AI agent framework — plugin-first, self-improving, multi-channel
+Author: OpenComputer Contributors
+License: MIT
+Keywords: agent,ai,anthropic,chatbot,claude,llm,openai
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: anthropic>=0.40
+Requires-Dist: discord-py>=2.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: mcp>=1.0
+Requires-Dist: openai>=1.60
+Requires-Dist: pydantic>=2.9
+Requires-Dist: python-frontmatter>=1.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: tenacity>=9.0
+Requires-Dist: typer>=0.12
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OpenComputer
+
+A personal AI agent framework — plugin-first, self-improving, multi-channel.
+
+A synthesis of the best ideas from [Claude Code](https://github.com/anthropics/claude-code), [Hermes Agent](https://github.com/NousResearch/hermes-agent), [OpenClaw](https://github.com/openclaw/openclaw), and [Kimi CLI](https://github.com/MoonshotAI/kimi-cli).
+
+## What it does
+
+- **Chat agent** with tool calling (file ops, bash, grep, glob, subagents, skills).
+- **Three-pillar persistent memory:** declarative (MEMORY.md), procedural (skills/), episodic (SQLite + FTS5 full-text search).
+- **Self-improvement loop:** the agent saves complex workflows as skills that auto-activate next time.
+- **Strict plugin SDK boundary:** third-party plugins never import core internals, so the core can evolve without breaking plugins.
+- **Multi-channel gateway:** run as a daemon; chat via Telegram and Discord today, Slack coming.
+- **Multiple providers:** Anthropic (native + proxy-compatible), OpenAI, any OpenAI-compatible endpoint (OpenRouter, Ollama, etc.).
+- **MCP integration:** plug in any [Model Context Protocol](https://modelcontextprotocol.io) server — its tools become native tools.
+
+## Status
+
+Pre-alpha (0.1.0). Core architecture stable. 114 tests passing. Adding features incrementally.
+
+## Install
+
+Requires **Python 3.12+**.
+
+```bash
+pip install opencomputer
+```
+
+### For development
+
+```bash
+git clone https://github.com/sakshamzip2-sys/opencomputer.git
+cd opencomputer
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```bash
+# 1. Run the setup wizard — picks provider, saves config
+opencomputer setup
+
+# 2. Export your API key (setup tells you which)
+export ANTHROPIC_API_KEY=sk-ant-...
+# or: export OPENAI_API_KEY=sk-...
+
+# 3. Verify the install
+opencomputer doctor
+
+# 4. Chat
+opencomputer
+```
+
+## Commands
+
+```bash
+opencomputer                 # start a chat session (alias for `chat`)
+opencomputer chat            # interactive REPL with tools
+opencomputer gateway         # run the daemon — listens on configured channels
+opencomputer search QUERY    # full-text search past conversations
+opencomputer sessions        # list recent sessions
+opencomputer skills          # list available skills (bundled + user)
+opencomputer plugins         # list installed plugins
+opencomputer setup           # first-run wizard
+opencomputer doctor          # diagnose config/env issues
+opencomputer config show     # print effective config
+opencomputer config get KEY  # read one config value (e.g. model.provider)
+opencomputer config set KEY VALUE
+```
+
+## Coding mode
+
+OpenComputer ships with a `coding-harness` plugin that adds Claude-Code-style
+coding tools (Edit, MultiEdit, TodoWrite, background process management) plus
+a formal "plan mode" that refuses destructive tools while you review the plan.
+
+```bash
+# Normal mode — Edit/Write/Bash work, agent can modify files directly
+opencomputer
+
+# Plan mode — agent describes what it would do, Edit/Write/Bash are refused
+# Useful for big refactors where you want to review before committing
+opencomputer chat --plan
+
+# Disable automatic context compaction (debugging long sessions)
+opencomputer chat --no-compact
+```
+
+In plan mode, plan-mode guidance is injected into the system prompt AND a
+PreToolUse hook hard-blocks destructive tools — belt + suspenders. Subagents
+spawned via the `delegate` tool inherit plan mode automatically.
+
+Remove the coding harness any time by removing or renaming
+`extensions/coding-harness/`. The core agent stays fully functional.
+
+## Messaging channels
+
+### Telegram
+
+1. Message [@BotFather](https://t.me/BotFather) → `/newbot` → get a token
+2. `export TELEGRAM_BOT_TOKEN=123:ABC...`
+3. `opencomputer gateway` — the bundled Telegram plugin auto-connects
+4. DM your bot on Telegram
+
+## MCP servers
+
+Plug any MCP server into OpenComputer. Edit `~/.opencomputer/config.yaml`:
+
+```yaml
+mcp:
+  servers:
+    - name: my-server
+      transport: stdio
+      command: python3
+      args:
+        - /path/to/mcp_server.py
+      enabled: true
+```
+
+The server's tools become available to the agent on next run (namespaced `my-server__tool_name`).
+
+## Architecture
+
+```
+opencomputer/   (core — agent loop, state, memory, tools, hooks, gateway, plugin discovery)
+plugin_sdk/     (public contract — stable types plugins import)
+extensions/     (bundled plugins — telegram, discord, anthropic-provider, openai-provider, coding-harness)
+```
+
+**Key design rule:** extensions import only from `plugin_sdk/*`, never from `opencomputer/*`. The core can be refactored freely without breaking plugins.
+
+## Writing a plugin
+
+Plugins are separate folders with a manifest and an entry module. Minimal channel plugin:
+
+```
+extensions/my-channel/
+├── plugin.json           # { "id": "my-channel", "version": "0.1.0", "entry": "plugin", "kind": "channel" }
+├── plugin.py             # exports register(api) — registers the adapter
+└── adapter.py            # your BaseChannelAdapter subclass
+```
+
+See `extensions/telegram/` for a working reference.
+
+## License
+
+MIT — see `LICENSE.md`.
+
+## Credits
+
+Architectural ideas synthesized from:
+- **Claude Code** — plugin primitives vocabulary (commands/skills/agents/hooks/MCP), lifecycle events
+- **Hermes Agent** — Python core patterns, three-pillar memory, agent loop shape
+- **OpenClaw** — plugin-first architecture, manifest-first discovery, strict SDK boundary
+- **Kimi CLI** — dynamic injection, fire-and-forget hooks, deferred MCP, wire-protocol UI decoupling