openmuse-agent 0.3.0a0__py3-none-any.whl

openmuse/__init__.py

@@ -0,0 +1,3 @@
+"""OpenMuse: a local-first personal agent runtime."""
+
+__version__ = "0.3.0a0"

openmuse/approval_ui.py

@@ -0,0 +1,14 @@
+"""Render a human-readable approval diff outside planner-controlled text."""
+
+import html
+
+from .models import Action
+
+
+def render_approval(action: Action, identity: str, destination: str, cost: str | None = None) -> str:
+    rows = "".join(
+        f"<tr><th>{html.escape(str(k))}</th><td>{html.escape(str(v))}</td></tr>"
+        for k, v in sorted(action.arguments.items())
+    )
+    cost_line = f"<p><strong>Cost:</strong> {html.escape(cost)}</p>" if cost else ""
+    return f"<main><h1>Approve action</h1><p><strong>Identity:</strong> {html.escape(identity)}</p><p><strong>Destination:</strong> {html.escape(destination)}</p>{cost_line}<p><strong>Tool:</strong> {html.escape(action.tool)}</p><table>{rows}</table><p>Approval expires and can be used once.</p></main>"

openmuse/approvals.py

@@ -0,0 +1,60 @@
+"""Host-issued, action-bound, expiring, one-time approvals."""
+
+import hashlib
+import hmac
+import json
+import threading
+import time
+from dataclasses import dataclass, field
+
+from .models import Action
+
+
+@dataclass
+class ApprovalAuthority:
+    """Issues and verifies one-time approval tokens.
+
+    Expiry contract: a token is expired when ``now >= exp``; the exact
+    boundary second is already invalid. Consumption is atomic: no
+    interleaving of concurrent ``verify`` calls can consume one token twice.
+    """
+
+    secret: bytes
+    used: set[str] = field(default_factory=set)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False, compare=False)
+
+    def issue(self, action: Action, ttl_seconds: int = 300) -> str:
+        payload = {
+            "id": action.id,
+            "tool": action.tool,
+            "arguments": action.arguments,
+            "exp": int(time.time()) + ttl_seconds,
+        }
+        raw = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
+        return raw.hex() + "." + hmac.new(self.secret, raw, hashlib.sha256).hexdigest()
+
+    def verify(self, action: Action, token: str | None) -> bool:
+        if not token:
+            return False
+        try:
+            raw_hex, sig = token.split(".", 1)
+            raw = bytes.fromhex(raw_hex)
+            p = json.loads(raw)
+        except (ValueError, TypeError, json.JSONDecodeError):
+            return False
+        if not isinstance(p, dict):
+            return False
+        expected = {"id": action.id, "tool": action.tool, "arguments": action.arguments, "exp": p.get("exp")}
+        try:
+            expired = int(p["exp"]) <= int(time.time())
+        except (KeyError, TypeError, ValueError):
+            return False
+        if expired or p != expected:
+            return False
+        if not hmac.compare_digest(sig, hmac.new(self.secret, raw, hashlib.sha256).hexdigest()):
+            return False
+        with self._lock:
+            if token in self.used:
+                return False
+            self.used.add(token)
+        return True

openmuse/audit.py

@@ -0,0 +1,64 @@
+"""Redacted, hash-chained JSONL audit trail."""
+
+import hashlib
+import json
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+SENSITIVE = {"password", "token", "secret", "authorization", "api_key", "cookie"}
+
+
+def redact(v: Any) -> Any:
+    if isinstance(v, Mapping):
+        return {k: ("[REDACTED]" if k.lower() in SENSITIVE else redact(x)) for k, x in v.items()}
+    if isinstance(v, list):
+        return [redact(x) for x in v]
+    return v
+
+
+class AuditLog:
+    def __init__(self, path: Path):
+        self.path = path
+
+    def append(self, record: dict[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        previous = "0" * 64
+        if self.path.exists():
+            lines = self.path.read_text(encoding="utf-8").splitlines()
+            previous = json.loads(lines[-1]).get("hash", previous) if lines else previous
+        clean = redact(record)
+        clean["previous_hash"] = previous
+        raw = json.dumps(clean, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+        clean["hash"] = hashlib.sha256(raw.encode()).hexdigest()
+        fd = os.open(self.path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+        with os.fdopen(fd, "a", encoding="utf-8") as h:
+            h.write(json.dumps(clean, ensure_ascii=False) + "\n")
+
+
+def verify_chain(path: Path) -> tuple[bool, int, str | None]:
+    """Independently recompute every link in an audit JSONL chain."""
+    previous = "0" * 64
+    count = 0
+    try:
+        for count, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+            record = json.loads(line)
+            claimed = record.pop("hash")
+            if record.get("previous_hash") != previous:
+                return False, count, "previous hash does not match"
+            raw = json.dumps(record, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+            actual = hashlib.sha256(raw.encode()).hexdigest()
+            if not hmac_compare(actual, claimed):
+                return False, count, "record hash does not match"
+            previous = claimed
+    except (OSError, KeyError, json.JSONDecodeError, TypeError) as exc:
+        return False, count, str(exc)
+    return True, count, None
+
+
+def hmac_compare(left: str, right: str) -> bool:
+    """Constant-time compare without expanding the public API surface."""
+    import hmac
+
+    return hmac.compare_digest(left, right)

openmuse/broker.py

@@ -0,0 +1,77 @@
+"""Secrets broker: tools receive secrets through a side channel.
+
+The planner proposes actions with ordinary arguments only. A tool that needs a
+secret declares `secret_name`; the broker resolves it from the vault at
+execution time and injects the plaintext into the tool's `run_with_secret`
+callback, which the vault wipes after use. Secret values therefore never appear
+in action arguments, tool manifests, planner context, or the audit log - only
+the access itself is audited, by name.
+"""
+
+from datetime import datetime, timezone
+from typing import Any, Protocol
+
+from .audit import AuditLog
+from .policy import Risk
+from .secrets import SecretVault
+from .tools import ManifestMixin
+
+
+class SecretConsumingTool(Protocol):
+    name: str
+    description: str
+    risk: Risk
+    secret_name: str
+
+    def manifest(self) -> dict[str, Any]: ...
+    def run_with_secret(self, secret: str, **kwargs: Any) -> str: ...
+
+
+class BrokerError(ValueError):
+    pass
+
+
+class _BrokeredTool(ManifestMixin):
+    def __init__(self, inner: SecretConsumingTool, vault: SecretVault, audit: AuditLog | None) -> None:
+        schema = dict(inner.manifest().get("schema") or {})
+        properties = schema.get("properties") or {}
+        if "secret" in properties or inner.secret_name in properties:
+            raise BrokerError("secret arguments are forbidden in tool schemas")
+        self.inner = inner
+        self.vault = vault
+        self.audit = audit
+        self.name = inner.name
+        self.description = inner.description
+        self.risk = inner.risk
+        self.schema = schema
+
+    def run(self, **kwargs: Any) -> str:
+        if "secret" in kwargs or self.inner.secret_name in kwargs:
+            raise BrokerError("secrets never arrive as action arguments")
+        box: dict[str, str] = {}
+
+        def consume(plaintext: str) -> None:
+            box["output"] = self.inner.run_with_secret(plaintext, **kwargs)
+
+        self.vault.use(self.inner.secret_name, consume)
+        if self.audit is not None:
+            self.audit.append(
+                {
+                    "event": "secret_access",
+                    "tool": self.name,
+                    "secret_name": self.inner.secret_name,
+                    "at": datetime.now(timezone.utc).isoformat(),
+                }
+            )
+        return box["output"]
+
+
+class SecretBroker:
+    """Wraps secret-consuming tools so the planner never sees raw secrets."""
+
+    def __init__(self, vault: SecretVault, audit: AuditLog | None = None) -> None:
+        self.vault = vault
+        self.audit = audit
+
+    def tool(self, inner: SecretConsumingTool) -> _BrokeredTool:
+        return _BrokeredTool(inner, self.vault, self.audit)

openmuse/browser_worker.py

@@ -0,0 +1,24 @@
+"""Policy envelope for a separately deployed browser worker."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+from urllib.parse import urlsplit
+
+
+@dataclass(frozen=True)
+class BrowserJob:
+    url: str
+    action: str
+    allowed_domains: frozenset[str]
+    read_only: bool = True
+
+
+class BrowserWorkerPolicy:
+    MUTATIONS: ClassVar[set[str]] = {"click", "fill", "submit", "upload", "download"}
+
+    def validate(self, job: BrowserJob) -> None:
+        host = urlsplit(job.url).hostname
+        if not host or host not in job.allowed_domains:
+            raise ValueError("domain outside worker allowlist")
+        if job.read_only and job.action in self.MUTATIONS:
+            raise ValueError("mutation blocked in read-only worker")

openmuse/channels/__init__.py

@@ -0,0 +1,4 @@
+from .base import Channel, IncomingMessage
+from .web import WebChannel
+
+__all__ = ["Channel", "IncomingMessage", "WebChannel"]

openmuse/channels/base.py

@@ -0,0 +1,17 @@
+"""Portable user-channel interface."""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class IncomingMessage:
+    channel: str
+    conversation_id: str
+    sender_id: str
+    text: str
+
+
+class Channel(Protocol):
+    def receive(self) -> IncomingMessage | None: ...
+    def send(self, conversation_id: str, text: str) -> str: ...

openmuse/channels/web.py

@@ -0,0 +1,21 @@
+"""Small in-process web-channel adapter for demos and tests."""
+
+from collections import deque
+
+from .base import IncomingMessage
+
+
+class WebChannel:
+    def __init__(self) -> None:
+        self.inbox: deque[IncomingMessage] = deque()
+        self.outbox: list[tuple[str, str]] = []
+
+    def submit(self, conversation_id: str, sender_id: str, text: str) -> None:
+        self.inbox.append(IncomingMessage("web", conversation_id, sender_id, text))
+
+    def receive(self) -> IncomingMessage | None:
+        return self.inbox.popleft() if self.inbox else None
+
+    def send(self, conversation_id: str, text: str) -> str:
+        self.outbox.append((conversation_id, text))
+        return f"web:{len(self.outbox)}"

openmuse/cli.py

@@ -0,0 +1,27 @@
+import argparse
+import json
+from pathlib import Path
+
+from .core import Agent
+from .models import Action
+from .policy import Policy
+from .tools import FetchURL, ReadFile, WriteFile
+
+
+def main():
+    p = argparse.ArgumentParser(prog="openmuse")
+    p.add_argument("tool", choices=["read_file", "write_file", "fetch_url"])
+    p.add_argument("--args", default="{}")
+    p.add_argument("--workspace", type=Path, default=Path.cwd())
+    p.add_argument("--allow-writes", action="store_true")
+    a = p.parse_args()
+    w = a.workspace.resolve()
+    r = Agent([ReadFile(w), WriteFile(w), FetchURL()], Policy(a.allow_writes), w / ".openmuse/audit.jsonl").execute(
+        Action(a.tool, json.loads(a.args))
+    )
+    print(r.output)
+    raise SystemExit(0 if r.status.value == "completed" else 2)
+
+
+if __name__ == "__main__":
+    main()

openmuse/connectors.py

@@ -0,0 +1,130 @@
+"""Scoped connectors: least-privilege declarations enforced at the boundary.
+
+A connector declares capabilities; each capability carries a scope string and a
+risk tier. The runtime only routes a call when the host has granted that exact
+scope to that connector, the grant is unexpired and unrevoked, and the action
+passes the policy layer like any other exact action. Grants can never exceed
+the connector's declared scopes.
+"""
+
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from .policy import Risk
+from .tools import ManifestMixin
+
+
+@dataclass(frozen=True)
+class Capability:
+    name: str
+    scope: str
+    risk: Risk
+    schema: dict[str, Any] = field(default_factory=lambda: {"type": "object"})
+
+
+class Connector(Protocol):
+    name: str
+
+    def capabilities(self) -> list[Capability]: ...
+    def invoke(self, capability: str, arguments: Mapping[str, Any]) -> str: ...
+
+
+class ConnectorLifecycle(Protocol):
+    """Optional lifecycle hook for connectors that retain local cached data."""
+
+    name: str
+
+    def delete_cached_data(self) -> None: ...
+
+
+@dataclass(frozen=True)
+class Grant:
+    scopes: frozenset[str]
+    expires_at: float | None = None
+
+
+class GrantError(ValueError):
+    pass
+
+
+class ScopeGrants:
+    """Host-owned grant ledger; the only writer of scope permissions."""
+
+    def __init__(self) -> None:
+        self._grants: dict[str, Grant] = {}
+
+    def grant(self, connector: Connector, scopes: set[str], ttl_seconds: int | None = None) -> Grant:
+        declared = {capability.scope for capability in connector.capabilities()}
+        if not scopes or not set(scopes) <= declared:
+            raise GrantError("grant exceeds the connector's declared scopes")
+        grant = Grant(
+            frozenset(scopes),
+            None if ttl_seconds is None else time.time() + ttl_seconds,
+        )
+        self._grants[connector.name] = grant
+        return grant
+
+    def revoke(self, connector_name: str) -> None:
+        self._grants.pop(connector_name, None)
+
+    def revoke_and_delete(self, connector: ConnectorLifecycle) -> None:
+        """Revoke authority before deleting connector-owned cached data.
+
+        If deletion fails, access stays revoked and the error is surfaced so the
+        host can retry cleanup without reopening the connector boundary.
+        """
+        self.revoke(connector.name)
+        connector.delete_cached_data()
+
+    def allows(self, connector_name: str, scope: str) -> bool:
+        grant = self._grants.get(connector_name)
+        if grant is None or scope not in grant.scopes:
+            return False
+        return grant.expires_at is None or time.time() < grant.expires_at
+
+
+class ScopeDenied(ValueError):
+    pass
+
+
+class ConnectorTool(ManifestMixin):
+    """Expose one connector capability as a policy-checked tool."""
+
+    def __init__(self, connector: Connector, capability: Capability, grants: ScopeGrants) -> None:
+        self.connector = connector
+        self.capability = capability
+        self.grants = grants
+        self.name = f"{connector.name}:{capability.name}"
+        self.description = f"Connector {connector.name} capability {capability.name} (scope {capability.scope})"
+        self.risk = capability.risk
+        self.schema = capability.schema
+
+    def run(self, **kwargs: Any) -> str:
+        if not self.grants.allows(self.connector.name, self.capability.scope):
+            raise ScopeDenied(f"scope not granted: {self.connector.name}/{self.capability.scope}")
+        return self.connector.invoke(self.capability.name, kwargs)
+
+
+def connector_tools(connector: Connector, grants: ScopeGrants) -> list[ConnectorTool]:
+    return [ConnectorTool(connector, capability, grants) for capability in connector.capabilities()]
+
+
+class ReadOnlyConnector:
+    """Base for read-only connectors: write and representation are undeclarable."""
+
+    name = "readonly"
+
+    def capabilities(self) -> list[Capability]:
+        declared = self.read_capabilities()
+        for capability in declared:
+            if capability.risk is not Risk.READ or not capability.scope.endswith(".read"):
+                raise GrantError("read-only connectors may only declare read capabilities")
+        return declared
+
+    def read_capabilities(self) -> list[Capability]:
+        raise NotImplementedError
+
+    def invoke(self, capability: str, arguments: Mapping[str, Any]) -> str:
+        raise NotImplementedError

openmuse/core.py

@@ -0,0 +1,65 @@
+import hashlib
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Protocol
+
+from .audit import AuditLog
+from .models import Action, ActionStatus, ToolResult
+from .policy import Policy
+from .registry import ToolRegistry
+from .validation import SchemaValidationError, validate_arguments
+
+
+class Planner(Protocol):
+    def plan(self, goal: str, tools: list[dict], history: list[ToolResult]) -> Action | None: ...
+
+
+class Agent:
+    def __init__(self, tools, policy: Policy, audit_log: Path) -> None:
+        self.registry = ToolRegistry(tools)
+        self.policy = policy
+        self.audit = AuditLog(audit_log)
+
+    def execute(self, action: Action) -> ToolResult:
+        tool = self.registry.get(action.tool)
+        if not tool:
+            return ToolResult(action.id, ActionStatus.FAILED, error_code="unknown_tool")
+        try:
+            validate_arguments(action.arguments, tool.manifest().get("schema"))
+        except SchemaValidationError as exc:
+            r = ToolResult(action.id, ActionStatus.FAILED, str(exc), "invalid_arguments")
+            self._audit(action, r)
+            return r
+        d = self.policy.check(tool.risk, action)
+        if not d.allowed:
+            r = ToolResult(action.id, ActionStatus.BLOCKED, d.reason, "approval_required")
+        else:
+            try:
+                r = ToolResult(action.id, ActionStatus.COMPLETED, str(tool.run(**dict(action.arguments))))
+            except (OSError, ValueError, TypeError, KeyError) as e:
+                r = ToolResult(action.id, ActionStatus.FAILED, str(e), type(e).__name__, False)
+        self._audit(action, r)
+        return r
+
+    def _audit(self, action: Action, result: ToolResult) -> None:
+        self.audit.append(
+            {
+                "at": datetime.now(timezone.utc).isoformat(),
+                "action": {"id": action.id, "tool": action.tool, "arguments": action.arguments},
+                "status": result.status.value,
+                "error_code": result.error_code,
+                "output_sha256": hashlib.sha256(result.output.encode()).hexdigest(),
+            }
+        )
+
+    def run(self, goal: str, planner: Planner, max_steps: int = 8) -> list[ToolResult]:
+        history: list[ToolResult] = []
+        for _ in range(max_steps):
+            action = planner.plan(goal, self.registry.catalogue(), history)
+            if action is None:
+                break
+            result = self.execute(action)
+            history.append(result)
+            if result.status in {ActionStatus.BLOCKED, ActionStatus.FAILED}:
+                break
+        return history

openmuse/effects.py

@@ -0,0 +1,39 @@
+"""Typed, approval-bound external effect proposals."""
+
+from dataclasses import dataclass
+from decimal import Decimal
+
+
+@dataclass(frozen=True)
+class MessageEffect:
+    identity: str
+    recipient: str
+    body: str
+    channel: str
+
+
+@dataclass(frozen=True)
+class ScheduleEffect:
+    identity: str
+    summary: str
+    starts_at: str
+    ends_at: str
+    attendees: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class PurchaseEffect:
+    merchant: str
+    currency: str
+    subtotal: Decimal
+    tax: Decimal
+    shipping: Decimal
+    fees: Decimal
+    total: Decimal
+    address_hint: str
+    payment_hint: str
+
+    def validate(self) -> None:
+        expected = self.subtotal + self.tax + self.shipping + self.fees
+        if expected != self.total:
+            raise ValueError(f"final total mismatch: {expected} != {self.total}")

openmuse/ephemeral.py

@@ -0,0 +1,32 @@
+"""One-time ephemeral values for OTP and credential-use grants."""
+
+import time
+from dataclasses import dataclass, field
+from uuid import uuid4
+
+
+@dataclass
+class EphemeralBroker:
+    values: dict[str, tuple[str, float, str]] = field(default_factory=dict)
+
+    def issue(self, value: str, purpose: str, ttl_seconds: int = 120) -> str:
+        handle = uuid4().hex
+        self.values[handle] = (value, time.time() + ttl_seconds, purpose)
+        return handle
+
+    def consume(self, handle: str, purpose: str) -> str:
+        value, expires, bound = self.values.pop(handle)
+        if bound != purpose or expires < time.time():
+            raise ValueError("ephemeral grant invalid or expired")
+        return value
+
+
+@dataclass(frozen=True)
+class CredentialUseGrant:
+    credential_handle: str
+    operation: str
+    origin: str
+    expires_at: float
+
+    def permits(self, operation: str, origin: str) -> bool:
+        return self.operation == operation and self.origin == origin and self.expires_at >= time.time()

openmuse/evidence.py

@@ -0,0 +1,31 @@
+"""Evidence, verification state, and bounded retry policy."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Verification(str, Enum):
+    VERIFIED = "verified"
+    UNVERIFIED = "unverified"
+    CONFLICTED = "conflicted"
+
+
+@dataclass(frozen=True)
+class Evidence:
+    claim: str
+    source_url: str | None
+    verification: Verification
+    observed_at: str
+    detail: str = ""
+
+
+@dataclass
+class RetryBudget:
+    maximum: int = 1
+    attempts: int = 0
+
+    def take(self, retryable: bool) -> bool:
+        if not retryable or self.attempts >= self.maximum:
+            return False
+        self.attempts += 1
+        return True