aria-code 0.167.0__py3-none-win_amd64.whl

aria_code/packages/aria_mcp/bridge.py

@@ -0,0 +1,232 @@
+"""Describe how Aria packages should be exposed over MCP."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List
+
+
+@dataclass(frozen=True)
+class MCPExposure:
+    name: str
+    target: str
+    description: str
+    read_only: bool = True
+
+    def to_tool_descriptor(self) -> Dict[str, object]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "target": self.target,
+            "read_only": self.read_only,
+        }
+
+
+def default_exposures() -> List[MCPExposure]:
+    """Initial MCP server surface for Aria Code.
+
+    These names are stable contracts. The server implementation can bind them
+    to ToolRegistry/AgentRegistry without changing client-facing tool names.
+    """
+
+    return [
+        MCPExposure("aria.warehouse.task", "agent:warehouse_navigation",
+            "Delegate a bounded simulation goal to the stateful warehouse task agent; it observes, plans, executes, replans and verifies. No hardware connection.", read_only=False),
+        MCPExposure("aria.market.quote", "tool:get_market_data", "Fetch quote and technical market snapshot."),
+        MCPExposure("aria.agent.team", "agent:team", "Run multi-agent financial research."),
+        MCPExposure("aria.report.generate", "tool:report_generate", "Fetch data + generate a full HTML research report artifact for a symbol.", read_only=False),
+        MCPExposure("aria.backtest.run", "tool:backtest_run", "Run a historical strategy simulation (buy_hold or sma_cross) against real price history.", read_only=False),
+        # Governance: what Aria knows about a change that another agent does not.
+        MCPExposure(
+            "aria.risk.assess",
+            "infra:risk",
+            "How risky is this action? Give a shell `command` (or a `tool` and its `params`) and get "
+            "its level L0-L4, the capabilities it uses (filesystem.write, package.install, git.push, "
+            "cloud.deploy, hardware.flash, actuator.command, ...), whether it can be undone, what it "
+            "reaches (hosts, files, systems) and whether it needs approval. Read-only: nothing runs.",
+        ),
+        MCPExposure(
+            "aria.contract.check",
+            "infra:contract",
+            "Would the project's change contract (.aria/policy.yaml) allow this tool call? Returns "
+            "allowed/blocked with the rule that decided it, and the contract in force. A project with "
+            "no contract allows everything; one whose policy cannot be read allows reads only. Read-only.",
+        ),
+        MCPExposure(
+            "aria.project.impact",
+            "infra:impact",
+            "What does changing these files or symbols reach? Dependents, tests and the services that "
+            "ship them, from the project's import graph. Use before editing code others depend on. Read-only.",
+        ),
+        MCPExposure(
+            "aria.project.commands",
+            "infra:commands",
+            "The project's own test, build, lint and simulation commands (from .aria/project.yaml, ROS 2 "
+            "packages, package.json, Cargo.toml, go.mod, pyproject.toml or Makefile targets). Read-only; "
+            "nothing is run and nothing is guessed.",
+        ),
+        MCPExposure("aria.artifacts.list", "infra:artifacts", "List local generated artifacts."),
+        MCPExposure(
+            "aria.skill.list",
+            "infra:skills",
+            "List the installed portable SKILL.md workflows — reusable expert playbooks "
+            "for design, research, and engineering tasks (e.g. UI design systems, "
+            "anti-generic-AI-look UI critique, trading-app patterns, equity research, "
+            "backtest validation). Pass `query` to rank by relevance to a task "
+            "description instead of listing everything.",
+        ),
+        MCPExposure(
+            "aria.skill.get",
+            "infra:skills",
+            "Fetch one skill's full instructions by name (from aria.skill.list). Returns "
+            "the SKILL.md workflow text for you to follow yourself — skills are "
+            "instruction documents, not executable tools, so nothing runs server-side. "
+            "The response lists any bundled `references` docs; when the instructions tell "
+            "you to read one, call this again with `reference` set to that filename.",
+        ),
+        MCPExposure("aria.broker.positions", "tool:broker_positions", "Read account info + positions for a configured broker."),
+        MCPExposure("aria.broker.list_previews", "tool:broker_list_previews", "List recent order previews, including TradingView-triggered ones."),
+        MCPExposure(
+            "aria.broker.preview_order",
+            "tool:broker_preview_order",
+            "Build a risk-checked order preview. Never executes a trade by itself — "
+            "actual execution needs either a human running /trade confirm in the aria-code "
+            "terminal, or aria.broker.confirm_order if the user explicitly opted that broker "
+            "into chat-confirmed execution (off by default; see aria.broker.confirm_order).",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.broker.confirm_order",
+            "tool:broker_confirm_order",
+            "Execute a previously built order preview — REAL MONEY. Refuses unless the user "
+            "already ran /trade allow-chat-confirm <broker_id> in the aria-code terminal "
+            "themselves (a real trade cannot be confirmed for the first time from chat; that "
+            "opt-in can only happen at the terminal keyboard) AND this call passes confirmed=true.",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.report.chart",
+            "tool:report_chart",
+            "Generate a candlestick + moving-average chart PNG for a symbol.",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.report.indicator_chart",
+            "tool:report_indicator_chart",
+            "Generate a candlestick + volume + RSI(14) + MACD(12,26,9) multi-panel chart "
+            "PNG for a symbol — for when you need the indicators plotted, not just price.",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.report.comparison_chart",
+            "tool:report_comparison_chart",
+            "Generate a normalized (base=100) % return comparison chart PNG across 2+ symbols.",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.report.allocation_chart",
+            "tool:report_allocation_chart",
+            "Generate a pie chart PNG of a broker account's position weights by market value.",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.report.pdf",
+            "tool:report_pdf",
+            "Render Markdown text to a styled PDF report.",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.report.canva_upload_asset",
+            "tool:canva_upload_asset",
+            "Upload a local image (e.g. a chart PNG from aria.report.chart) to Canva and "
+            "return its asset_id, for use in aria.report.canva_design's data field. "
+            "Requires /canva connect to have been run first.",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.report.estimate_image_cost",
+            "tool:openai_estimate_image_cost",
+            "Get an illustrative per-image cost estimate (USD) for OpenAI's gpt-image-1 "
+            "at a given size/quality, before generating. Free, no API call to OpenAI.",
+        ),
+        MCPExposure(
+            "aria.report.generate_image",
+            "tool:openai_generate_image",
+            "Generate a new image from a text prompt (e.g. minimal-editorial-poster's "
+            "compiled prompt) via OpenAI's gpt-image-1. Real per-call cost, billed by "
+            "OpenAI the instant this succeeds — requires confirmed=true, and calling "
+            "aria.report.estimate_image_cost first is strongly recommended. Requires an "
+            "OpenAI API key (/apikey set openai sk-... or OPENAI_API_KEY).",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.report.edit_image",
+            "tool:openai_edit_image",
+            "Transform an existing local photo per a text prompt (duotone, background "
+            "simplification, texture overlay, etc.) via OpenAI's gpt-image-1 edits "
+            "endpoint. Pass mask_path for inpainting — a local mask PNG where transparent "
+            "areas mark what to edit and opaque areas are left untouched — to constrain "
+            "the edit to part of the image instead of the whole thing. Real per-call cost, "
+            "billed by OpenAI the instant this succeeds — requires confirmed=true, and "
+            "calling aria.report.estimate_image_cost first is strongly recommended. "
+            "Requires an OpenAI API key.",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.report.generate_image_local",
+            "tool:local_generate_image",
+            "Generate a new image from a text prompt entirely locally via a self-hosted "
+            "open-weight model (SDXL-Turbo by default) — no API key, no per-call cost, "
+            "runs on this machine. Needs the optional 'image_gen' extra installed. "
+            "First call for a given model downloads its weights (several GB).",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.report.edit_image_local",
+            "tool:local_edit_image",
+            "Transform an existing local photo per a text prompt, entirely locally "
+            "(image-to-image, no API key). Needs the optional 'image_gen' extra installed.",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.report.canva_design",
+            "tool:canva_autofill",
+            "Fill a Canva brand template with data and export the design draft. "
+            "Requires /canva connect to have been run first.",
+            read_only=False,
+        ),
+        MCPExposure("aria.report.docx", "tool:report_docx", "Render Markdown text to an editable Word document.", read_only=False),
+        MCPExposure("aria.report.pptx", "tool:report_pptx", "Render Markdown text to an editable slide deck (one slide per heading).", read_only=False),
+        MCPExposure("aria.figma.read_file", "tool:figma_read_file", "Read a Figma file's page/frame structure (depth-limited summary, not the full node tree). Read-only — Figma has no API for writing designs."),
+        MCPExposure("aria.figma.comments", "tool:figma_comments", "List comments on a Figma file."),
+        MCPExposure("aria.video.probe", "tool:video_probe", "Read a video's duration/resolution/codec info."),
+        MCPExposure("aria.video.trim", "tool:video_trim", "Cut a [start, end] second range out of a local video.", read_only=False),
+        MCPExposure("aria.video.concat", "tool:video_concat", "Concatenate multiple local videos in order.", read_only=False),
+        MCPExposure("aria.video.overlay_text", "tool:video_overlay_text", "Burn a text overlay onto a local video (top/bottom/center).", read_only=False),
+        MCPExposure("aria.video.overlay_audio", "tool:video_overlay_audio", "Add or replace a local video's audio track.", read_only=False),
+        MCPExposure("aria.video.convert", "tool:video_convert", "Convert a local video's format and/or reframe to a target aspect ratio (e.g. 9:16 for vertical).", read_only=False),
+        MCPExposure("aria.video.change_speed", "tool:video_change_speed", "Speed up or slow down a local video (pitch-corrected audio).", read_only=False),
+        MCPExposure("aria.video.transcribe", "tool:video_transcribe", "Transcribe a local video's speech track entirely locally (faster-whisper, no API key). Needs the optional 'video_analysis' extra installed."),
+        MCPExposure("aria.video.detect_scenes", "tool:video_detect_scenes", "Detect scene-cut timestamps in a local video via frame-histogram comparison. Needs the optional 'video' extra (opencv) installed."),
+        MCPExposure(
+            "aria.video.generate_estimate",
+            "tool:video_generate_estimate",
+            "Get an illustrative cost estimate (USD) for a cloud AI video generation job on "
+            "'kling' or 'runway', before submitting. Free, no API call to the provider.",
+        ),
+        MCPExposure(
+            "aria.video.generate_submit",
+            "tool:video_generate_submit",
+            "Submit a real cloud AI text-to-video generation job on 'kling' or 'runway'. "
+            "Real per-request cost (billed by the provider the instant this succeeds) — requires "
+            "confirmed=true, and calling aria.video.generate_estimate first is strongly recommended. "
+            "Returns a task_id immediately; poll with aria.video.generate_status (generation takes minutes).",
+            read_only=False,
+        ),
+        MCPExposure(
+            "aria.video.generate_status",
+            "tool:video_generate_status",
+            "Check a submitted cloud video generation job's status; downloads the result once "
+            "succeeded. Checking status costs nothing beyond the original submission.",
+        ),
+    ]

aria_code/packages/aria_mcp/circuit.py

@@ -0,0 +1,82 @@
+"""Per-server circuit breaker for MCP calls (pure, clock-injectable).
+
+The contract's mcp-layer next step calls for per-server failure isolation and
+a reconnect policy. Without it, a dead or wedged MCP server costs every call
+its full request timeout (30s by default) forever — one bad server degrades
+the whole tool loop for the rest of the session.
+
+Classic three-state breaker:
+
+  closed     → calls flow; consecutive failures are counted
+  open       → calls fail fast (no subprocess I/O) until the cooldown elapses
+  half_open  → after cooldown, exactly one probe call is allowed through;
+               success closes the circuit, failure re-opens it for another
+               cooldown
+
+Pure state machine — no asyncio, no I/O; ``clock`` is injectable so tests
+can drive time deterministically.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Callable
+
+
+@dataclass
+class ServerCircuit:
+    failure_threshold: int = 3
+    cooldown_seconds: float = 60.0
+    clock: Callable[[], float] = time.monotonic
+
+    _failures: int = field(default=0, repr=False)
+    _open_until: float = field(default=0.0, repr=False)
+    _probing: bool = field(default=False, repr=False)
+
+    @property
+    def state(self) -> str:
+        if self._failures < self.failure_threshold:
+            return "closed"
+        if self.clock() < self._open_until:
+            return "open"
+        return "half_open"
+
+    @property
+    def failures(self) -> int:
+        return self._failures
+
+    def seconds_until_probe(self) -> float:
+        return max(0.0, self._open_until - self.clock())
+
+    def allow_call(self) -> bool:
+        """Whether a call may proceed now (half-open admits a single probe)."""
+        s = self.state
+        if s == "closed":
+            return True
+        if s == "open":
+            return False
+        # half_open: admit one probe at a time
+        if self._probing:
+            return False
+        self._probing = True
+        return True
+
+    def record_success(self) -> None:
+        self._failures = 0
+        self._open_until = 0.0
+        self._probing = False
+
+    def record_failure(self) -> None:
+        self._failures += 1
+        self._probing = False
+        if self._failures >= self.failure_threshold:
+            self._open_until = self.clock() + self.cooldown_seconds
+
+    def describe(self) -> str:
+        s = self.state
+        if s == "open":
+            return f"open ({self._failures} consecutive failures; probe in {self.seconds_until_probe():.0f}s)"
+        if s == "half_open":
+            return f"half_open ({self._failures} consecutive failures; probing)"
+        return f"closed ({self._failures} recent failures)"

aria_code/packages/aria_mcp/config.py

@@ -0,0 +1,162 @@
+"""MCP configuration helpers for Aria and Arthera package bridges."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+def financial_service_server_config(python: Path) -> Dict[str, object]:
+    """A separately installed finance service; never install or run code here."""
+    python = Path(python).expanduser()
+    if not python.is_absolute() or not python.is_file():
+        raise ValueError("Provide an absolute path to the financial-service Python interpreter")
+    # -I (isolated mode): the server is spawned in the user's workspace, and a
+    # plain `-m` puts the current directory first on sys.path, so a planted
+    # arthera_finance/ or a stdlib-named .py there would run in its place. -I
+    # also ignores PYTHON* variables and the user site directory.
+    #
+    # No "env": an entry here overrides the host's environment, so a pinned
+    # FINANCIAL_SERVICE_NETWORK=0 meant market data and brokers could never be
+    # enabled. The service itself defaults to offline; the host decides.
+    return {"name": "arthera-finance", "command": str(python),
+            "args": ["-I", "-m", "arthera_finance.server"],
+            "description": "Shared financial analysis and simulation; offline by default",
+            "enabled": True}
+
+
+def install_financial_service_config(path: Path, python: Path) -> Path:
+    """Explicit host operation: preserve other servers and replace config atomically."""
+    server = financial_service_server_config(python)
+    path = Path(path)
+    existing = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {"servers": []}
+    if (not isinstance(existing, dict) or not isinstance(existing.get("servers", []), list)
+            or any(not isinstance(item, dict) for item in existing.get("servers", []))):
+        raise ValueError("MCP configuration must contain a list of server objects")
+    merged = merge_server_config(existing, server)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = None
+    try:
+        with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=path.parent,
+                                         prefix=".finance-mcp-", delete=False) as stream:
+            temporary = Path(stream.name)
+            json.dump(merged, stream, ensure_ascii=False, indent=2)
+            stream.write("\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+    return path
+
+
+def arthera_quant_engine_server_config(
+    arthera_root: Optional[Path] = None,
+) -> Dict[str, object]:
+    """Return a ready-to-write MCP server entry for Arthera QuantEngine."""
+
+    configured = arthera_root or os.getenv("ARTHERA_ROOT", "").strip()
+    if not configured:
+        raise ValueError("The private backend bridge requires an explicit ARTHERA_ROOT; use /finance setup for the standalone financial-service.")
+    root = Path(configured).expanduser()
+    if not root.is_absolute():
+        raise ValueError("ARTHERA_ROOT must be an absolute path.")
+    server = root / "packages" / "quant_engine" / "mcp_server.py"
+    configured_python = os.getenv("ARTHERA_MCP_PYTHON", "").strip()
+    candidates = [
+        Path(configured_python).expanduser() if configured_python else None,
+        root / ".venv-mcp" / "bin" / "python",
+        root / ".venv" / "bin" / "python",
+        Path(sys.executable),
+    ]
+    python = next((path for path in candidates if path and path.exists()), Path("python3"))
+    return {
+        "name": "arthera_quant_engine",
+        "command": str(python),
+        "args": [str(server)],
+        "env": {"PYTHONPATH": str(root), "PYTHONUNBUFFERED": "1"},
+        "description": "Arthera QuantEngine tools exposed through MCP",
+        "enabled": True,
+    }
+
+
+def merge_server_config(existing: Dict[str, object], server: Dict[str, object]) -> Dict[str, object]:
+    """Return config with server upserted by name."""
+
+    servers = list(existing.get("servers") or [])
+    name = server.get("name")
+    out = []
+    replaced = False
+    for item in servers:
+        item_name = item.get("name") if isinstance(item, dict) else None
+        is_legacy_arthera = name == "arthera_quant_engine" and item_name == "quant_engine"
+        if isinstance(item, dict) and (item_name == name or is_legacy_arthera):
+            if not replaced:
+                out.append(server)
+                replaced = True
+        else:
+            out.append(item)
+    if not replaced:
+        out.append(server)
+    return {**existing, "servers": out}
+
+
+def load_mcp_config(path: Path) -> Dict[str, object]:
+    if not path.exists():
+        return {"servers": []}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {"servers": []}
+
+
+def write_mcp_config(path: Path, config: Dict[str, object]) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(config, ensure_ascii=False, indent=2), encoding="utf-8")
+    return path
+
+
+def find_server_config(config: Dict[str, object], name: str) -> Optional[Dict[str, object]]:
+    for item in config.get("servers") or []:
+        if isinstance(item, dict) and item.get("name") == name:
+            return item
+    return None
+
+
+def mcp_server_status(
+    config_path: Path,
+    server_name: str = "arthera_quant_engine",
+    runtime_status: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    """Return config/file/runtime status for a configured MCP server."""
+
+    config = load_mcp_config(config_path)
+    server = find_server_config(config, server_name)
+    runtime = None
+    for item in runtime_status or []:
+        if item.get("name") == server_name:
+            runtime = item
+            break
+
+    server_path = None
+    if server:
+        args = server.get("args") or []
+        if args:
+            server_path = Path(str(args[0])).expanduser()
+
+    return {
+        "name": server_name,
+        "config_path": str(config_path),
+        "configured": server is not None,
+        "server_path": str(server_path) if server_path else "",
+        "server_file_exists": bool(server_path and server_path.exists()),
+        "running": bool(runtime and runtime.get("running")),
+        "tool_count": int(runtime.get("tool_count", 0)) if runtime else 0,
+        "tools": list(runtime.get("tools", [])) if runtime else [],
+        "description": (server or {}).get("description", ""),
+    }

aria_code/packages/aria_mcp/installer.py

@@ -0,0 +1,95 @@
+"""
+src/aria_code/packages/aria_mcp/installer.py — One-Click MCP Config Installer for VS Code & Cursor
+==================================================================================================
+Automatically detects and registers aria-code MCP server into:
+1. VS Code / VS Code Insiders (`settings.json` or `.vscode/mcp.json`)
+2. Cursor IDE (`settings.json`)
+3. Claude Desktop (`claude_desktop_config.json`)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+
+def get_ide_config_paths() -> Dict[str, Path]:
+    """Return standard config paths by platform."""
+    home = Path.home()
+    system = platform.system()
+
+    if system == "Darwin":  # macOS
+        return {
+            "vscode": home / "Library" / "Application Support" / "Code" / "User" / "settings.json",
+            "cursor": home / "Library" / "Application Support" / "Cursor" / "User" / "settings.json",
+            "claude": home / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",
+        }
+    elif system == "Windows":
+        appdata = Path(os.environ.get("APPDATA", str(home / "AppData" / "Roaming")))
+        return {
+            "vscode": appdata / "Code" / "User" / "settings.json",
+            "cursor": appdata / "Cursor" / "User" / "settings.json",
+            "claude": appdata / "Claude" / "claude_desktop_config.json",
+        }
+    else:  # Linux
+        config_dir = Path(os.environ.get("XDG_CONFIG_HOME", str(home / ".config")))
+        return {
+            "vscode": config_dir / "Code" / "User" / "settings.json",
+            "cursor": config_dir / "Cursor" / "User" / "settings.json",
+            "claude": config_dir / "Claude" / "claude_desktop_config.json",
+        }
+
+
+def generate_mcp_entry(server_path: Optional[str] = None) -> Dict[str, Any]:
+    """Generate canonical MCP server registration block."""
+    if not server_path:
+        # Default to invoking aria-code via sys.executable or command
+        return {
+            "command": "aria-code",
+            "args": ["mcp"],
+        }
+    return {
+        "command": sys.executable,
+        "args": [server_path],
+    }
+
+
+def install_mcp_to_target(target: str = "vscode", custom_path: Optional[Path] = None) -> Tuple[bool, str]:
+    """
+    Install aria-code MCP configuration to specified target editor.
+    Returns (success, status_message).
+    """
+    paths = get_ide_config_paths()
+    config_file = custom_path or paths.get(target.lower())
+
+    if not config_file:
+        return False, f"Unknown target: {target}. Valid targets: vscode, cursor, claude"
+
+    try:
+        config_file.parent.mkdir(parents=True, exist_ok=True)
+        data: Dict[str, Any] = {}
+        if config_file.exists():
+            try:
+                with open(config_file, "r", encoding="utf-8") as f:
+                    content = f.read().strip()
+                    if content:
+                        data = json.loads(content)
+            except Exception as e:
+                return False, f"Failed to parse existing JSON in {config_file}: {e}"
+
+        # Insert or update mcpServers dict
+        if "mcpServers" not in data:
+            data["mcpServers"] = {}
+
+        data["mcpServers"]["aria-code"] = generate_mcp_entry()
+
+        with open(config_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+        return True, f"Successfully registered aria-code MCP server to {config_file}"
+    except Exception as e:
+        return False, f"Error writing to {config_file}: {e}"