opencomputer 0.1.0__py3-none-any.whl

opencomputer-0.1.0.dist-info/RECORD

@@ -0,0 +1,51 @@
+opencomputer/__init__.py,sha256=gO2dZNgM6MLxz2pdq32RGQTD2vS27TpPASlsIMAb2TI,75
+opencomputer/cli.py,sha256=Cb7BrTIwGZS1cb-_RAaMJXkXGgkSPoY9ryue5Dco2I0,16277
+opencomputer/doctor.py,sha256=eyQDj1h6GYfwLxljjTlhQoyBDPwtIipOP8pPXyRNTqI,6752
+opencomputer/setup_wizard.py,sha256=g-PFyayuu18s_3HXr3beR1Lbz4BcWg2vXUpVtwwevPI,8370
+opencomputer/agent/__init__.py,sha256=rk4klIVmYuO_obiwCK1bsmrbKLH4VnLGRhi18zgzV90,64
+opencomputer/agent/compaction.py,sha256=1W_3TrAFPSJBk8_26F9dWd2IZ7n5NoyDRCBWx9C3F-c,9374
+opencomputer/agent/config.py,sha256=60cW2Dyv-YPFf6E_ZNQn9xb85RwbgdamvKpleCKNRtk,3150
+opencomputer/agent/config_store.py,sha256=Ep1JCs1-A2fY8a_VfHksiQcMaCiaiU4TGccJgE2RdJQ,7360
+opencomputer/agent/injection.py,sha256=CuNxfKCauIphSWJpO9js_cT6CMBPyWAa1fz4uI_15ig,2101
+opencomputer/agent/loop.py,sha256=b_ip9eqfJ70kpZTmZLF8CHRbMu_fKWSEq5PsJ13ihOk,12356
+opencomputer/agent/memory.py,sha256=DmjpEZxdPHK03Udevicwwzrxhg0xGJcSNbCr0nLLlAQ,4939
+opencomputer/agent/prompt_builder.py,sha256=1_UqCBQx1WYTPITPptj-vyMpNYWpl9SP3goFeI4Tb9A,1825
+opencomputer/agent/state.py,sha256=R1DamH-auT7SqvpopexEuzP5wxOJ3UmmMwgxVnVkvq8,8953
+opencomputer/agent/step.py,sha256=gP0ByNVqeKU-PFAeI1Jlct1iSGXotg5l3Wb7lIxarEQ,823
+opencomputer/agent/prompts/base.j2,sha256=DPR9XNJetxULTLOicUEdDEd7eT6UraAzTRsJJuPExrs,770
+opencomputer/gateway/__init__.py,sha256=SbMLVhBOYJCRpPPXbJuLj5R-jpkv7eJmJtBzXxXlHBo,59
+opencomputer/gateway/dispatch.py,sha256=X5RTO_pYIN60duU1eSFQ8qGeZn2e9qqsLklxpI_z1MY,3351
+opencomputer/gateway/protocol.py,sha256=ccGdrxYOXjN-UVhBp8d1bTZQbUTrnDggDsnR7iPUtIE,2666
+opencomputer/gateway/server.py,sha256=TePY6S2WRPSz8ZQxb1vmbDMSkPObLy-P8tMNGDSCSag,2717
+opencomputer/gateway/wire_server.py,sha256=CeVlF-2WhQ0zTIboFMgjmbNNnD4G330VCYEq6fIoj14,8366
+opencomputer/hooks/__init__.py,sha256=ppxxhfzdZj16u3Wk3RD0RxKvK-sE0ZexY8v1XgwKSLc,50
+opencomputer/hooks/engine.py,sha256=PYs7GYAW8ztFbG8CDOLWEa7oN17oYhzsRge2iJu5pB8,2589
+opencomputer/hooks/runner.py,sha256=_nBl67kBG5Qt7UpLqQvb15-wYL-xye1497EOVdJqK6Y,1108
+opencomputer/mcp/__init__.py,sha256=OidTJFlWyzy7km3k9wDnNXzHrnJzAUcitwY0QcBkd9M,85
+opencomputer/mcp/client.py,sha256=WvA1ovIyQ6A5EA28Wv5d5cr4S-TXIIlW-AcRQUgBceE,7582
+opencomputer/plugins/__init__.py,sha256=gNdUELzcu3CZyS-xhE6hn6utS4Q9l20Nvly4DDx33eI,78
+opencomputer/plugins/discovery.py,sha256=JjKOLRQbSzCKrDcgp_TREHvq_APsNwNak7yBUFpMNd4,3307
+opencomputer/plugins/loader.py,sha256=o_IkpLG6GLayyiyfg0SayuTNS-BRG-wzKaeXkaUKp-Q,5376
+opencomputer/plugins/registry.py,sha256=nOzE1ehcHvpoGrgvyqmOYADe0xY6lZwM60xiF7sTWUY,1992
+opencomputer/skills/debug-python-import-error/SKILL.md,sha256=jBL3sHwtI-4rXbZC92qC5YV7xmP_fkVKGPETIaK5Pvw,2268
+opencomputer/tools/__init__.py,sha256=ZbX8aocncUzMpXQ0sJNZc1Waxu_c0SZInSR3vLMlV5A,80
+opencomputer/tools/bash.py,sha256=ZymfpRnir_9GbUWsTJy4BgmTcZeoDA22cz9mGciZMDE,2770
+opencomputer/tools/delegate.py,sha256=Yn55lUnjlGzjUdoI9RWpHTm0vH_lNMll53l4N0RgW8c,3962
+opencomputer/tools/glob.py,sha256=JXl814MKY0O9hvAfzCqrr38xxXzurQ7Zk7j7fa54L_w,2369
+opencomputer/tools/grep.py,sha256=PCz1xqSNCbU6_guLIwkv_Dj-w1v_zqT7okul4vRmv4k,4081
+opencomputer/tools/read.py,sha256=FRpVndWdb7I09yF5v-GXOE71oqjfe1Vs6dwQbyY2DcU,2855
+opencomputer/tools/registry.py,sha256=97niCcd7cuMtPql4Wilrtf6bv1kayqsedPiyDXd2cco,2190
+opencomputer/tools/skill_manage.py,sha256=CZjBCfkfil8-YAL9jO4AuLRMbfFoQz9NsL4fyjbD9rs,10212
+opencomputer/tools/write.py,sha256=704Qjng-SCj3MlIJu7uul8vSTU1dH_2pkQ9Fsda-Y9g,2010
+plugin_sdk/__init__.py,sha256=UCsA-Of-gdrXdQBXxzFdkYKZ0o64nWcpBnsANCXRCMs,1604
+plugin_sdk/channel_contract.py,sha256=MJ9iaPG7QMTRD3orKkKtKSUtS-kCjEeNc--snl1NrRg,2448
+plugin_sdk/core.py,sha256=mulzBrjhcvPXTvjLrl0Q8sEhnZWZeq2NuG0G8vkrBQw,3683
+plugin_sdk/hooks.py,sha256=nhvjd4qM7T0BZ2G-G5N70VReJ0mHkCyOxKh5TguQ1JY,2589
+plugin_sdk/injection.py,sha256=r2WPZYPcoaYn1gzOLzb9Ni5ZDbNkNg8brFsJySXr9jw,2056
+plugin_sdk/provider_contract.py,sha256=hybjR2AhPRs3rv-1XavaJOP5U4KXkuQ3lt667dOESaE,2716
+plugin_sdk/runtime_context.py,sha256=UOfEsAnIvM5LtX0DVZqw67HvH83KinYQTp8KpAzUUZk,1381
+plugin_sdk/tool_contract.py,sha256=YJ0AsjhG8EiBeTfB5MwHu6nQ8wN16p7vPiBTT9vGas4,1944
+opencomputer-0.1.0.dist-info/METADATA,sha256=TrL-2aVSZ5STLC30LfWRtG00uuml65klT8XXlG3zUpU,6669
+opencomputer-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+opencomputer-0.1.0.dist-info/entry_points.txt,sha256=hvAtUBkItM2YqIhOp3Kh3tOc5tRAM3qAZBn-qG0gzCo,82
+opencomputer-0.1.0.dist-info/RECORD,,

opencomputer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

opencomputer-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+oc = opencomputer.cli:main
+opencomputer = opencomputer.cli:main

plugin_sdk/__init__.py

@@ -0,0 +1,66 @@
+"""
+OpenComputer Plugin SDK — the ONLY public contract for plugins.
+
+Third-party plugins must import from `plugin_sdk/*` exclusively. Never
+import from `opencomputer/**` directly — those modules are internal
+and may change without warning. The SDK is versioned and evolves with
+backwards-compatible guarantees across minor releases.
+"""
+
+__version__ = "0.1.0"
+
+from plugin_sdk.channel_contract import BaseChannelAdapter
+from plugin_sdk.core import (
+    Message,
+    MessageEvent,
+    Platform,
+    PluginManifest,
+    Role,
+    SendResult,
+    StopReason,
+    ToolCall,
+    ToolResult,
+)
+from plugin_sdk.hooks import HookContext, HookDecision, HookEvent, HookHandler, HookSpec
+from plugin_sdk.injection import DynamicInjectionProvider, InjectionContext
+from plugin_sdk.provider_contract import (
+    BaseProvider,
+    ProviderResponse,
+    StreamEvent,
+    Usage,
+)
+from plugin_sdk.runtime_context import DEFAULT_RUNTIME_CONTEXT, RuntimeContext
+from plugin_sdk.tool_contract import BaseTool, ToolSchema
+
+__all__ = [
+    "__version__",
+    # core types
+    "Role",
+    "Message",
+    "ToolCall",
+    "ToolResult",
+    "Platform",
+    "MessageEvent",
+    "SendResult",
+    "PluginManifest",
+    "StopReason",
+    # contracts
+    "BaseTool",
+    "ToolSchema",
+    "BaseProvider",
+    "ProviderResponse",
+    "StreamEvent",
+    "Usage",
+    "BaseChannelAdapter",
+    # hooks
+    "HookEvent",
+    "HookContext",
+    "HookDecision",
+    "HookHandler",
+    "HookSpec",
+    # runtime + injection
+    "RuntimeContext",
+    "DEFAULT_RUNTIME_CONTEXT",
+    "DynamicInjectionProvider",
+    "InjectionContext",
+]

plugin_sdk/channel_contract.py

@@ -0,0 +1,74 @@
+"""
+Channel contract — what plugin authors implement to add a messaging channel.
+
+A channel adapter translates between a specific messaging platform
+(Telegram, Discord, Slack, ...) and OpenComputer's common MessageEvent
+format. The gateway is platform-agnostic; adapters absorb all the
+platform-specific weirdness.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from plugin_sdk.core import MessageEvent, Platform, SendResult
+
+
+class BaseChannelAdapter(ABC):
+    """Base class for a messaging channel plugin."""
+
+    #: The platform this adapter serves.
+    platform: Platform
+
+    #: Max message length this platform accepts (in chars unless noted).
+    max_message_length: int = 10_000
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.config = config
+        self._message_handler: (
+            Callable[[MessageEvent], Awaitable[str | None]] | None
+        ) = None
+
+    def set_message_handler(
+        self, handler: Callable[[MessageEvent], Awaitable[str | None]]
+    ) -> None:
+        """Called by the gateway to register its inbound handler."""
+        self._message_handler = handler
+
+    async def handle_message(self, event: MessageEvent) -> None:
+        """Adapters call this when an inbound message arrives. Dispatches to the gateway."""
+        if self._message_handler is None:
+            return
+        response = await self._message_handler(event)
+        if response:
+            await self.send(event.chat_id, response)
+
+    @abstractmethod
+    async def connect(self) -> bool:
+        """Connect to the platform and start listening. Return True on success."""
+        ...
+
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Stop listening and clean up."""
+        ...
+
+    @abstractmethod
+    async def send(self, chat_id: str, text: str, **kwargs: Any) -> SendResult:
+        """Send a text message to a chat."""
+        ...
+
+    async def send_typing(self, chat_id: str) -> None:
+        """Send a typing indicator. Optional — default is a no-op."""
+        return None
+
+    async def send_image(
+        self, chat_id: str, image_url: str, caption: str = ""
+    ) -> SendResult:
+        """Send an image. Optional — default raises NotImplementedError."""
+        raise NotImplementedError(f"{self.platform} adapter has no image support")
+
+
+__all__ = ["BaseChannelAdapter"]

plugin_sdk/core.py

@@ -0,0 +1,129 @@
+"""
+Core public types — the canonical vocabulary plugins use.
+
+These types are the STABLE contract. Changes here are breaking changes
+and require a major version bump of plugin_sdk.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Literal
+
+# ─── Message / conversation primitives ─────────────────────────────────
+
+Role = Literal["system", "user", "assistant", "tool"]
+
+
+@dataclass(frozen=True, slots=True)
+class Message:
+    """A single conversation message — canonical form used everywhere internally."""
+
+    role: Role
+    content: str
+    tool_call_id: str | None = None
+    tool_calls: list[ToolCall] | None = None
+    name: str | None = None  # for tool messages, the tool name
+    reasoning: str | None = None  # extended thinking, if supported
+
+
+@dataclass(frozen=True, slots=True)
+class ToolCall:
+    """A request from the model to invoke a tool."""
+
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ToolResult:
+    """The result of executing a tool call."""
+
+    tool_call_id: str
+    content: str
+    is_error: bool = False
+
+
+# ─── Platform / channel primitives ─────────────────────────────────────
+
+
+class Platform(str, Enum):
+    """Supported messaging platforms. Plugins can register new ones."""
+
+    CLI = "cli"
+    TELEGRAM = "telegram"
+    DISCORD = "discord"
+    SLACK = "slack"
+    WHATSAPP = "whatsapp"
+    SIGNAL = "signal"
+    IMESSAGE = "imessage"
+    WEB = "web"
+
+
+@dataclass(frozen=True, slots=True)
+class MessageEvent:
+    """Platform-agnostic inbound message — the common format produced by every adapter."""
+
+    platform: Platform
+    chat_id: str
+    user_id: str
+    text: str
+    timestamp: float  # unix timestamp
+    attachments: list[str] = field(default_factory=list)  # file paths or URLs
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class SendResult:
+    """Outbound delivery result from a channel adapter."""
+
+    success: bool
+    message_id: str | None = None
+    error: str | None = None
+
+
+# ─── Plugin manifest ───────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class PluginManifest:
+    """Metadata for a plugin — parsed from plugin.json at discovery time."""
+
+    id: str
+    name: str
+    version: str
+    description: str = ""
+    author: str = ""
+    homepage: str = ""
+    license: str = "MIT"
+    kind: Literal["channel", "provider", "tool", "skill", "mixed"] = "mixed"
+    entry: str = ""  # path to the entry module, relative to plugin root
+
+
+# ─── Stop reasons ──────────────────────────────────────────────────────
+
+
+class StopReason(str, Enum):
+    """Why a conversation step ended."""
+
+    END_TURN = "end_turn"  # model produced final response, no more tool calls
+    TOOL_USE = "tool_use"  # model wants to call tools — loop continues
+    MAX_TOKENS = "max_tokens"  # hit output limit
+    INTERRUPTED = "interrupted"  # user cancelled
+    BUDGET_EXHAUSTED = "budget_exhausted"  # iteration budget spent
+    ERROR = "error"  # unrecoverable error
+
+
+__all__ = [
+    "Role",
+    "Message",
+    "ToolCall",
+    "ToolResult",
+    "Platform",
+    "MessageEvent",
+    "SendResult",
+    "PluginManifest",
+    "StopReason",
+]

plugin_sdk/hooks.py

@@ -0,0 +1,80 @@
+"""
+Hook primitives — for plugins that want to intercept lifecycle events.
+
+Hooks are fire-and-forget event handlers. Critical rule (from kimi-cli):
+post-action hooks MUST NOT block the agent loop. Use async + let the
+loop move on. The hook engine discards exceptions silently (logs them).
+
+Available events:
+    PreToolUse       — fires before any tool runs (can approve/block/modify)
+    PostToolUse      — fires after any tool runs (log, inspect result)
+    Stop             — fires when the model stops asking for tools (can force continue)
+    SessionStart     — fires once when a new conversation begins
+    SessionEnd       — fires when conversation ends
+    UserPromptSubmit — fires when the user submits a message
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+from plugin_sdk.core import Message, ToolCall, ToolResult
+from plugin_sdk.runtime_context import RuntimeContext
+
+
+class HookEvent(str, Enum):
+    PRE_TOOL_USE = "PreToolUse"
+    POST_TOOL_USE = "PostToolUse"
+    STOP = "Stop"
+    SESSION_START = "SessionStart"
+    SESSION_END = "SessionEnd"
+    USER_PROMPT_SUBMIT = "UserPromptSubmit"
+
+
+@dataclass(frozen=True, slots=True)
+class HookContext:
+    """Data passed to every hook invocation. Read-only."""
+
+    event: HookEvent
+    session_id: str
+    tool_call: ToolCall | None = None
+    tool_result: ToolResult | None = None
+    message: Message | None = None
+    #: Runtime flags for this invocation (plan_mode, yolo_mode, custom).
+    #: None for backwards compatibility with hooks written before this field.
+    runtime: RuntimeContext | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HookDecision:
+    """A hook's response. PreToolUse hooks use `decision` to approve/block."""
+
+    decision: Literal["approve", "block", "pass"] = "pass"
+    reason: str = ""
+    modified_message: str = ""  # if set, injected as a system reminder
+
+
+# Hook handler is an async callable: (ctx) -> HookDecision or None (= "pass")
+HookHandler = Callable[[HookContext], Awaitable[HookDecision | None]]
+
+
+@dataclass(frozen=True, slots=True)
+class HookSpec:
+    """What plugins register — one event + one handler + an optional matcher."""
+
+    event: HookEvent
+    handler: HookHandler
+    matcher: str | None = None  # regex over tool names for PreToolUse/PostToolUse
+    fire_and_forget: bool = True  # true for post-action hooks
+
+
+__all__ = [
+    "HookEvent",
+    "HookContext",
+    "HookDecision",
+    "HookHandler",
+    "HookSpec",
+]

plugin_sdk/injection.py

@@ -0,0 +1,60 @@
+"""
+Dynamic injection providers — cross-cutting system-prompt modifiers.
+
+A provider declares a piece of text to inject into the system prompt when
+certain runtime conditions apply (e.g. plan mode active). The agent loop
+queries all registered providers at the start of each turn; whichever
+return non-empty strings get appended to the system prompt.
+
+This is kimi-cli's pattern — keeps cross-cutting concerns (plan mode, yolo
+mode, custom modes) out of the main loop as if-branches.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from plugin_sdk.core import Message
+from plugin_sdk.runtime_context import RuntimeContext
+
+
+@dataclass(frozen=True, slots=True)
+class InjectionContext:
+    """Read-only snapshot passed to each provider's collect() call."""
+
+    #: Full message history so far (same list the LLM will see this turn).
+    messages: tuple[Message, ...]
+    #: Per-invocation flags (plan_mode, yolo_mode, etc.).
+    runtime: RuntimeContext
+    #: Session id — useful for session-scoped caches or per-chat behaviors.
+    session_id: str = ""
+
+
+class DynamicInjectionProvider(ABC):
+    """Base class for providers that inject text into the system prompt.
+
+    Implement `collect()`. Return a string (the injection) or None/empty
+    (this provider is not applicable this turn).
+
+    `priority` orders providers in the final prompt — lower first.
+    `provider_id` must be unique per registration; it's also used for
+    deterministic ordering when two providers share a priority.
+    """
+
+    #: Lower runs first. Plan mode is 10, yolo is 20, user-added modes 50+.
+    priority: int = 100
+
+    @property
+    @abstractmethod
+    def provider_id(self) -> str:
+        """Unique id per provider. Used for dedup + ordering stability."""
+        ...
+
+    @abstractmethod
+    def collect(self, ctx: InjectionContext) -> str | None:
+        """Return injection text or None if this provider doesn't apply."""
+        ...
+
+
+__all__ = ["DynamicInjectionProvider", "InjectionContext"]

plugin_sdk/provider_contract.py

@@ -0,0 +1,95 @@
+"""
+Provider contract — what plugin authors implement to add an LLM provider.
+
+Providers wrap model APIs (Anthropic, OpenAI, OpenRouter, etc.) behind a
+single interface the agent loop depends on. The agent never imports
+anthropic/openai SDKs directly — it only uses BaseProvider.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Literal
+
+from plugin_sdk.core import Message
+from plugin_sdk.tool_contract import ToolSchema
+
+
+@dataclass(frozen=True, slots=True)
+class Usage:
+    """Token counts from a single LLM call."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderResponse:
+    """The result of calling `provider.complete(...)`."""
+
+    message: Message  # the assistant message, possibly containing tool_calls
+    stop_reason: str  # "end_turn" | "tool_use" | "max_tokens" | ...
+    usage: Usage
+
+
+@dataclass(frozen=True, slots=True)
+class StreamEvent:
+    """One event emitted by `provider.stream_complete()`.
+
+    Types:
+      - "text_delta": incremental text chunk (`text` field)
+      - "tool_call": full tool call has been assembled (`tool_call` field)
+      - "done": streaming finished (`response` field carries the final ProviderResponse)
+    """
+
+    kind: Literal["text_delta", "tool_call", "done"]
+    text: str = ""
+    response: ProviderResponse | None = None
+
+
+class BaseProvider(ABC):
+    """Base class for an LLM provider plugin."""
+
+    name: str = ""
+    default_model: str = ""
+
+    @abstractmethod
+    async def complete(
+        self,
+        *,
+        model: str,
+        messages: list[Message],
+        system: str = "",
+        tools: list[ToolSchema] | None = None,
+        max_tokens: int = 4096,
+        temperature: float = 1.0,
+        stream: bool = False,
+    ) -> ProviderResponse:
+        """Send messages to the provider, return a single ProviderResponse."""
+        ...
+
+    @abstractmethod
+    async def stream_complete(
+        self,
+        *,
+        model: str,
+        messages: list[Message],
+        system: str = "",
+        tools: list[ToolSchema] | None = None,
+        max_tokens: int = 4096,
+        temperature: float = 1.0,
+    ) -> AsyncIterator[StreamEvent]:
+        """Stream the response.
+
+        Yields StreamEvent objects in order. Final event has kind="done"
+        and carries the complete ProviderResponse (including aggregated text
+        and any tool calls). Text chunks arrive as kind="text_delta".
+        """
+        ...
+
+
+__all__ = ["BaseProvider", "ProviderResponse", "Usage", "StreamEvent"]

plugin_sdk/runtime_context.py

@@ -0,0 +1,39 @@
+"""
+RuntimeContext — per-turn flags passed through the agent loop.
+
+The CLI / caller builds this once per invocation. The agent loop passes it
+to InjectionProviders (so they can decide whether to fire) and to Hooks
+(so they can decide whether to block). `delegate` propagates it to
+subagents, so modes like `--plan` apply to the whole subagent tree.
+
+Frozen dataclass — safe to share across tasks / threads.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeContext:
+    """Flags that cross-cutting modes read. Immutable per invocation."""
+
+    #: Plan mode — agent should describe what it would do without executing
+    #: destructive tools. Enforced both via injection (prompt) and hook (hard-block).
+    plan_mode: bool = False
+
+    #: Yolo mode — auto-approve dangerous operations. Mutually exclusive with plan_mode
+    #: (we enforce this in the CLI; if both set, plan_mode wins).
+    yolo_mode: bool = False
+
+    #: Escape hatch for third-party plugins to add their own modes without
+    #: forcing an SDK version bump.
+    custom: dict[str, Any] = field(default_factory=dict)
+
+
+#: A sentinel "no flags" default — useful when callers don't care about modes.
+DEFAULT_RUNTIME_CONTEXT = RuntimeContext()
+
+
+__all__ = ["RuntimeContext", "DEFAULT_RUNTIME_CONTEXT"]

plugin_sdk/tool_contract.py

@@ -0,0 +1,67 @@
+"""
+Tool contract — what plugin authors implement to add a new tool.
+
+A tool is any callable the agent can invoke: Read, Write, Bash, etc.
+Plugins can add new ones by subclassing `BaseTool` and registering
+via `register_plugin(..., tools=[MyTool])`.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+from plugin_sdk.core import ToolCall, ToolResult
+
+
+@dataclass(frozen=True, slots=True)
+class ToolSchema:
+    """OpenAI-compatible JSON schema for a tool."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]  # JSON Schema object
+
+    def to_openai_format(self) -> dict[str, Any]:
+        """Convert to the dict format the OpenAI API expects."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def to_anthropic_format(self) -> dict[str, Any]:
+        """Convert to the dict format the Anthropic API expects."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.parameters,
+        }
+
+
+class BaseTool(ABC):
+    """Base class for a tool. Subclass and implement `schema` + `execute`."""
+
+    #: Whether this tool is safe to run in parallel with other parallel-safe tools.
+    parallel_safe: bool = False
+
+    #: Maximum size of the result string (longer is truncated with a notice).
+    max_result_size: int = 100_000
+
+    @property
+    @abstractmethod
+    def schema(self) -> ToolSchema:
+        """Return the JSON schema describing this tool's input."""
+        ...
+
+    @abstractmethod
+    async def execute(self, call: ToolCall) -> ToolResult:
+        """Actually run the tool. Must handle its own errors — never raise."""
+        ...
+
+
+__all__ = ["ToolSchema", "BaseTool"]