runspace 0.2.0__py3-none-any.whl

runspace/__init__.py

@@ -0,0 +1,11 @@
+"""Runspace — a workspace runtime for LLM agents.
+
+Subpackages:
+    contracts     wire shapes shared between a host app and an agent runtime
+    protocols     swappable adapters behind typing.Protocol definitions
+    workspace     the workspace product: gateway, registry, runtimes
+    ingestion     inbound channels
+    helpers       session, messaging and document utilities
+"""
+
+__version__ = "0.2.0"

runspace/contracts/__init__.py

@@ -0,0 +1,69 @@
+"""Runtime-agnostic contracts.
+
+Pydantic shapes + schema validators that any runtime (agentino,
+openclaw, future) must produce/consume to participate in the workspace
+chat protocol. No agentino framework imports here — that's the
+load-bearing rule.
+
+Migrated from `workspace/backend/models.py` (2026-05-06) so a second
+runtime can import the wire shapes without dragging in WorkspaceGateway
++ AppRegistry + the agentino Agent class.
+"""
+
+from .chat import (
+    AttachmentInput,
+    ChatRequest,
+    ChatResponse,
+    FileAttachmentResponse,
+    RoutineCreateRequest,
+    RoutineDelivery,
+)
+from .runtime import AgentRuntime, AgentTurnDelta, AgentTurnResult, Attachment
+from .scheduling import (
+    CronJob,
+    Delivery,
+    JobStatus,
+    Payload,
+    Schedule,
+    ScheduleKind,
+)
+from .tool import AgentTool
+from .workspace import (
+    AppConfig,
+    ChannelConfig,
+    ProviderConfig,
+    UserConfig,
+    WorkspaceConfig,
+    load_workspace,
+)
+
+__all__ = [
+    # chat protocol
+    "AttachmentInput",
+    "ChatRequest",
+    "ChatResponse",
+    "FileAttachmentResponse",
+    "RoutineCreateRequest",
+    "RoutineDelivery",
+    # tool contract
+    "AgentTool",
+    # runtime contract (the dispatcher seam)
+    "AgentRuntime",
+    "AgentTurnResult",
+    "AgentTurnDelta",
+    "Attachment",
+    # workspace.yml schema
+    "AppConfig",
+    "ChannelConfig",
+    "ProviderConfig",
+    "UserConfig",
+    "WorkspaceConfig",
+    "load_workspace",
+    # scheduling primitives
+    "CronJob",
+    "Delivery",
+    "JobStatus",
+    "Payload",
+    "Schedule",
+    "ScheduleKind",
+]

runspace/contracts/chat.py

@@ -0,0 +1,80 @@
+"""Wire shapes for the workspace chat protocol.
+
+Both agentino's WorkspaceGateway and any future runtime's HTTP layer
+produce/consume these. Pure data — no framework imports.
+
+Originally lived at `workspace/backend/models.py`; moved 2026-05-06 to
+make it a runtime-agnostic contract.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class AttachmentInput(BaseModel):
+    name: str
+    type: str  # MIME type
+    size: int  # bytes
+    content: str = ""  # base64-encoded file content (text files decoded for agent)
+
+
+class ChatRequest(BaseModel):
+    app_id: str | None = None
+    agent_id: str | None = None  # alias for app_id (backward compat)
+    message: str = ""
+    session_id: str = ""
+    thread_id: str | None = None
+    sender_name: str | None = None  # real user name from JWT (per-request identity)
+    file_ids: list[str] = []  # uploaded file references (from /upload endpoint)
+    # Legacy (still supported)
+    media_base64: str | None = None
+    media_mime: str | None = None
+    attachments: list[AttachmentInput] = []
+
+    @property
+    def resolved_app_id(self) -> str:
+        return self.app_id or self.agent_id or ""
+
+
+class FileAttachmentResponse(BaseModel):
+    name: str
+    url: str
+    size: int
+    type: str
+
+
+class ChatResponse(BaseModel):
+    app_id: str
+    app_name: str
+    response: str
+    session_id: str
+    tools_used: list[str] = []
+    attachments: list[FileAttachmentResponse] = []
+
+
+class RoutineDelivery(BaseModel):
+    """Where (if anywhere) the agent's reply goes when a routine fires.
+
+    Three modes:
+      - channel: post to a chat channel (target = channel slug)
+      - dm:      send as a direct message (target = user_id)
+      - silent:  run the prompt, don't post anywhere (target ignored).
+                 The agent still uses tools and has side effects via
+                 those tools; only the *announce* part is suppressed.
+    """
+
+    kind: Literal["channel", "dm", "silent"]
+    target: str | None = None
+
+
+class RoutineCreateRequest(BaseModel):
+    agent_id: str
+    schedule: str
+    prompt: str
+    description: str = ""
+    enabled: bool = True
+    # Required. Caller picks where the routine's output lands.
+    delivery: RoutineDelivery

runspace/contracts/runtime.py

@@ -0,0 +1,94 @@
+"""AgentRuntime contract — the seam each runtime implements.
+
+Mirrors the Protocol that lives today at
+`acme/platform/apps/api/agent_runtime/protocol.py`. Lifting it here
+means a third-party host (acme, initech, future) can declare
+"my dispatcher accepts any AgentRuntime" without depending on acme's
+internal module.
+
+Pure data + Protocol. No imports beyond stdlib + dataclasses.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class Attachment:
+    """File attachment carried into a turn (e.g. a scanned invoice)."""
+
+    file_id: str
+    original_name: str
+    mime_type: str
+    size_bytes: int
+
+
+@dataclass
+class AgentTurnDelta:
+    """One streaming chunk from a runtime."""
+
+    text: str = ""
+    is_final: bool = False
+    tool_call: dict | None = None
+
+
+@dataclass
+class AgentTurnResult:
+    """Final result of one agent turn — runtime-agnostic."""
+
+    text: str
+    runtime: str  # "agentino" | "openclaw" | ...
+    tool_calls: list[dict] = field(default_factory=list)
+    runtime_session_id: str | None = None
+    duration_ms: int = 0
+    cost_usd: float | None = None
+    error: str | None = None
+
+
+@runtime_checkable
+class AgentRuntime(Protocol):
+    """Every runtime that can serve an agent turn implements this.
+
+    The dispatcher (`AgentRuntimeRouter` in acme) holds a map
+    `{name: AgentRuntime}` and calls `run_turn(...)` on whichever
+    runtime the tenant's `workspace.yml apps.<id>.type:` resolves to.
+    """
+
+    name: str  # canonical id: "agentino" | "openclaw"
+
+    async def run_turn(
+        self,
+        *,
+        tenant_id: str,
+        agent_id: str,
+        session_key: str,
+        message: str,
+        attachments: list[Attachment] | None = None,
+        sender_id: str | None = None,
+        channel: str | None = None,
+    ) -> AgentTurnResult: ...
+
+    async def stream_turn(
+        self,
+        *,
+        tenant_id: str,
+        agent_id: str,
+        session_key: str,
+        message: str,
+        attachments: list[Attachment] | None = None,
+        sender_id: str | None = None,
+        channel: str | None = None,
+    ) -> AsyncIterator[AgentTurnDelta]:
+        """Optional. Subprocess-based runtimes may yield a single final delta."""
+        ...
+
+
+__all__ = [
+    "AgentRuntime",
+    "AgentTurnResult",
+    "AgentTurnDelta",
+    "Attachment",
+]

runspace/contracts/scheduling.py

@@ -0,0 +1,239 @@
+"""Scheduling primitives — runtime-agnostic data shapes.
+
+Schedule, Payload, Delivery, CronJob and friends are pure dataclasses
+that any runtime can produce or consume. They live here (not in the
+agentino runtime) so that workspace gateway / routine stores can speak
+the same vocabulary regardless of which runtime is hosting an agent.
+
+agentino's `agentino.scheduler.core` re-exports these for back-compat
+so existing `from agentino.scheduler import Schedule, ...` keeps working.
+The runtime piece (`CronScheduler`) stays inside agentino — only the
+data layer moves.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from enum import Enum
+
+from croniter import croniter
+
+
+class JobStatus(Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    DISABLED = "disabled"
+
+
+class ScheduleKind(Enum):
+    AT = "at"
+    CRON = "cron"
+    EVERY = "every"
+
+
+@dataclass
+class Schedule:
+    kind: ScheduleKind
+    at: datetime | None = None
+    cron_expr: str | None = None
+    every_ms: int | None = None
+    timezone: str = "Europe/Nicosia"
+
+    def next_run(self, after: datetime | None = None) -> datetime | None:
+        after = after or datetime.now()
+        if self.kind == ScheduleKind.AT:
+            if self.at and self.at > after:
+                return self.at
+            return None
+        if self.kind == ScheduleKind.CRON:
+            if self.cron_expr:
+                try:
+                    cron = croniter(self.cron_expr, after)
+                    return cron.get_next(datetime)
+                except Exception:
+                    return None
+        if self.kind == ScheduleKind.EVERY:
+            if self.every_ms:
+                return after + timedelta(milliseconds=self.every_ms)
+        return None
+
+
+@dataclass
+class Delivery:
+    channel: str = "whatsapp"
+    to: str | None = None
+    best_effort: bool = True
+
+
+@dataclass
+class Payload:
+    kind: str
+    skill: str | None = None
+    template: str | None = None
+    message: str | None = None
+    data: dict = field(default_factory=dict)
+
+
+@dataclass
+class CronJob:
+    id: str
+    tenant_id: str
+    name: str
+    schedule: Schedule
+    payload: Payload
+    delivery: Delivery | None = None
+
+    enabled: bool = True
+    status: JobStatus = JobStatus.PENDING
+    delete_after_run: bool = False
+
+    created_at: datetime = field(default_factory=datetime.now)
+    next_run_at: datetime | None = None
+    last_run_at: datetime | None = None
+    last_error: str | None = None
+
+    consecutive_failures: int = 0
+    retry_after: datetime | None = None
+
+    def __post_init__(self):
+        if self.next_run_at is None:
+            self.next_run_at = self.schedule.next_run()
+
+    def calculate_retry_delay(self) -> timedelta:
+        delays = [30, 60, 300, 900, 3600]
+        idx = min(self.consecutive_failures, len(delays) - 1)
+        return timedelta(seconds=delays[idx])
+
+    def mark_success(self):
+        self.status = JobStatus.COMPLETED
+        self.last_run_at = datetime.now()
+        self.last_error = None
+        self.consecutive_failures = 0
+        self.retry_after = None
+        if self.schedule.kind != ScheduleKind.AT:
+            self.next_run_at = self.schedule.next_run(self.last_run_at)
+            self.status = JobStatus.PENDING
+        else:
+            if self.delete_after_run:
+                pass
+            else:
+                self.enabled = False
+
+    def mark_failure(self, error: str):
+        self.status = JobStatus.FAILED
+        self.last_run_at = datetime.now()
+        self.last_error = error
+        self.consecutive_failures += 1
+        delay = self.calculate_retry_delay()
+        self.retry_after = datetime.now() + delay
+        if self.schedule.kind != ScheduleKind.AT:
+            self.next_run_at = self.retry_after
+            self.status = JobStatus.PENDING
+
+    def is_due(self, now: datetime | None = None) -> bool:
+        now = now or datetime.now()
+        if not self.enabled:
+            return False
+        if self.status == JobStatus.RUNNING:
+            return False
+
+        def to_naive(dt):
+            if dt is None:
+                return None
+            return dt.replace(tzinfo=None) if dt.tzinfo else dt
+
+        now_naive = to_naive(now)
+        if self.retry_after and now_naive < to_naive(self.retry_after):
+            return False
+        if self.next_run_at and now_naive >= to_naive(self.next_run_at):
+            return True
+        return False
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "tenant_id": self.tenant_id,
+            "name": self.name,
+            "schedule_kind": self.schedule.kind.value,
+            "schedule_at": self.schedule.at.isoformat() if self.schedule.at else None,
+            "schedule_cron": self.schedule.cron_expr,
+            "schedule_every_ms": self.schedule.every_ms,
+            "schedule_timezone": self.schedule.timezone,
+            "payload_kind": self.payload.kind,
+            "payload_skill": self.payload.skill,
+            "payload_template": self.payload.template,
+            "payload_message": self.payload.message,
+            "payload_data": self.payload.data,
+            "delivery_channel": self.delivery.channel if self.delivery else None,
+            "delivery_to": self.delivery.to if self.delivery else None,
+            "delivery_best_effort": self.delivery.best_effort if self.delivery else True,
+            "enabled": self.enabled,
+            "status": self.status.value,
+            "delete_after_run": self.delete_after_run,
+            "created_at": self.created_at.isoformat(),
+            "next_run_at": self.next_run_at.isoformat() if self.next_run_at else None,
+            "last_run_at": self.last_run_at.isoformat() if self.last_run_at else None,
+            "last_error": self.last_error,
+            "consecutive_failures": self.consecutive_failures,
+            "retry_after": self.retry_after.isoformat() if self.retry_after else None,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> CronJob:
+        def _parse_dt(val):
+            if not val:
+                return None
+            dt = datetime.fromisoformat(val) if isinstance(val, str) else val
+            return dt.replace(tzinfo=None) if dt.tzinfo else dt
+
+        schedule = Schedule(
+            kind=ScheduleKind(data["schedule_kind"]),
+            at=_parse_dt(data.get("schedule_at")),
+            cron_expr=data.get("schedule_cron"),
+            every_ms=data.get("schedule_every_ms"),
+            timezone=data.get("schedule_timezone", "Europe/Nicosia"),
+        )
+        payload = Payload(
+            kind=data["payload_kind"],
+            skill=data.get("payload_skill"),
+            template=data.get("payload_template"),
+            message=data.get("payload_message"),
+            data=data.get("payload_data", {}),
+        )
+        delivery = None
+        if data.get("delivery_channel"):
+            delivery = Delivery(
+                channel=data["delivery_channel"],
+                to=data.get("delivery_to"),
+                best_effort=data.get("delivery_best_effort", True),
+            )
+        return cls(
+            id=data["id"],
+            tenant_id=data["tenant_id"],
+            name=data["name"],
+            schedule=schedule,
+            payload=payload,
+            delivery=delivery,
+            enabled=data.get("enabled", True),
+            status=JobStatus(data.get("status", "pending")),
+            delete_after_run=data.get("delete_after_run", False),
+            created_at=_parse_dt(data.get("created_at")) or datetime.now(),
+            next_run_at=_parse_dt(data.get("next_run_at")),
+            last_run_at=_parse_dt(data.get("last_run_at")),
+            last_error=data.get("last_error"),
+            consecutive_failures=data.get("consecutive_failures", 0),
+            retry_after=_parse_dt(data.get("retry_after")),
+        )
+
+
+__all__ = [
+    "JobStatus",
+    "ScheduleKind",
+    "Schedule",
+    "Delivery",
+    "Payload",
+    "CronJob",
+]

runspace/contracts/tool.py

@@ -0,0 +1,68 @@
+"""AgentTool contract — runtime-agnostic tool interface.
+
+The structural shape every runtime's "tool" must satisfy. Both
+agentino's `@tool`-decorated `Tool` (Python) and openclaw's
+`api.registerTool({ name, parameters, execute })` (TypeScript) fit
+this contract. Defining it here means:
+
+1. Documentation: the field set is fixed, agreed across runtimes.
+   Adding a tool = "ship something that satisfies AgentTool".
+2. Tooling: validators / schema generators can target the contract
+   without importing a specific runtime's implementation.
+3. Future runtimes: a third runtime knows what to expose from day one.
+
+This is a Protocol, not a base class — Tool / OpenClaw factory don't
+inherit from it; they satisfy it structurally. Runtime-checkable so
+`isinstance(t, AgentTool)` works for sanity checks if needed.
+
+This module deliberately has zero runtime dependencies — it imports
+only from typing and collections.abc. The contract is pure shape.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class AgentTool(Protocol):
+    """The minimal contract a runtime's "tool" must satisfy.
+
+    Mandatory fields:
+      - `name`: unique identifier the LLM uses to call the tool.
+      - `description`: human + model-readable summary; the LLM picks
+        tools by reading this.
+      - `parameters`: JSON-Schema dict (or compatible) describing input
+        args. Both agentino's pydantic-ish dict and openclaw's TypeBox
+        schemas serialize to JSON Schema.
+      - `fn` (or callable interface): the actual logic. May be sync or
+        async. Implementations may also expose `execute(...)` (openclaw
+        style) — runtimes-side adapters bridge whichever shape they use
+        to a common call: `tool(args) -> result`.
+
+    Optional behavioural metadata:
+      - `is_read_only`: marks the tool as side-effect-free (safe for
+        parallel execution, retry, dry-run).
+      - `timeout`: per-call timeout in seconds.
+
+    Notes:
+      - The contract intentionally does NOT prescribe permissions / gates
+        — those live in `agents.gates` (workspace.yml) and are enforced
+        at the runtime layer, not per-tool.
+      - The contract uses `Any` for the result on purpose. Tools return
+        strings, dicts, structured envelopes (`{content: [...]}`) — each
+        runtime's caller normalises before passing to the LLM. Pinning a
+        type here would force runtimes to converge on a single
+        normalisation, which is premature.
+    """
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    fn: Callable[..., Any] | Callable[..., Awaitable[Any]]
+    is_read_only: bool
+    timeout: float | None
+
+
+__all__ = ["AgentTool"]

runspace/contracts/workspace.py

@@ -0,0 +1,91 @@
+"""Workspace.yml schema — runtime-agnostic validation + access.
+
+Both agentino (when AppRegistry loads a tenant) and openclaw (when its
+sync script reads each agent's metadata) consume the same workspace.yml.
+This module defines the schema in pydantic + a minimal loader.
+
+Goal: when a third runtime arrives, it imports `WorkspaceConfig` from
+here and gets the same view of `apps:`, `users:`, `channels:`,
+`routines:`, etc. without copying the parser.
+
+Lightweight on purpose — full validation is enforced at use-time
+(AppRegistry raises if `soul:` doesn't resolve, etc.). This schema
+exists to prevent typos and document the shape.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml  # type: ignore[import-untyped]
+from pydantic import BaseModel, Field
+
+
+class AppConfig(BaseModel):
+    """One agent in the `apps:` block of workspace.yml."""
+
+    name: str = ""
+    role: str = ""
+    avatar: str = ""
+    color: str = ""
+    group: Literal["backoffice", "customer", "default"] = "default"
+    type: Literal["agentino", "openclaw", "codex", "claude_code", "pi", "http", "webhook"] = (
+        "agentino"
+    )
+    soul: str | None = None
+    tools: str | None = None
+    shared_tools: str | list[str] | None = None
+    model: str | None = None
+    endpoint: str | None = None
+    enabled: bool = True
+    gates: dict[str, Any] | None = None
+    # New runtime-side fields used by openclaw
+    openclaw_plugin: str | None = None
+    openclaw_skills: list[str] = Field(default_factory=list)
+
+
+class UserConfig(BaseModel):
+    name: str = ""
+    role: str = ""
+    avatar: str = ""
+    default: bool = False
+
+
+class ChannelConfig(BaseModel):
+    id: str
+    label: str = ""
+    icon: str = ""
+    type: str = "chat"
+
+
+class ProviderConfig(BaseModel):
+    base_url: str = ""
+    api_key: str = ""
+    provider: str = ""
+
+
+class WorkspaceConfig(BaseModel):
+    """Top-level workspace.yml shape. `extra='allow'` because tenants
+    legitimately add custom blocks (settings, automation, persona…)
+    that are read by tenant-specific code paths."""
+
+    name: str = ""
+    icon: str = ""
+    brand_color: str = ""
+    sidebar_color: str = ""
+    tenant_id: str | None = None
+    apps: dict[str, AppConfig] = Field(default_factory=dict)
+    users: dict[str, UserConfig] = Field(default_factory=dict)
+    channels: list[ChannelConfig] = Field(default_factory=list)
+    providers: dict[str, ProviderConfig] = Field(default_factory=dict)
+
+    model_config = {"extra": "allow"}
+
+
+def load_workspace(path: str | Path) -> WorkspaceConfig:
+    """Read + validate a workspace.yml. Raises pydantic ValidationError
+    on shape errors. Pure I/O + parse, no runtime side effects."""
+    p = Path(path)
+    raw = yaml.safe_load(p.read_text(encoding="utf-8")) or {}
+    return WorkspaceConfig.model_validate(raw)