clio-relay 0.9.0__tar.gz

clio_relay-0.9.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.ruff_cache/
+.pytest_cache/
+.pyright/
+__pycache__/
+*.pyc
+.clio-relay/
+.tools/
+dist/
+build/
+*.egg-info/

clio_relay-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaime Cernuda Garcia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clio_relay-0.9.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: clio-relay
+Version: 0.9.0
+Summary: Cluster relay endpoints backed by clio-core and JARVIS-CD.
+Project-URL: Homepage, https://github.com/iowarp/clio-relay
+Project-URL: Repository, https://github.com/iowarp/clio-relay
+Project-URL: Issues, https://github.com/iowarp/clio-relay/issues
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: filelock>=3.15
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.8
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: websockets>=16.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/clio-relay-banner.png" alt="clio-relay banner">
+</p>
+
+<h1 align="center">clio-relay</h1>
+
+`clio-relay` lets a desktop tool submit work to a remote cluster, follow it while it runs, and collect logs, artifacts, progress, and provenance without putting job state in the network tunnel.
+
+It is a piece of the federation layer for [`clio-agent`](https://github.com/iowarp/clio-agent): a local CLIO experience can delegate work to a remote machine, keep observing it, detach, reconnect, and clean up after itself. The project is also designed for use outside CLIO. Any client that can call the CLI, HTTP API, or MCP tools can use the same relay model.
+
+## How It Works
+
+`clio-relay` has three long-running roles:
+
+- `desktop`: submits work and exposes CLI, HTTP, and MCP surfaces for local tools.
+- `worker`: runs on a configured cluster, leases work, invokes JARVIS-CD, and records results.
+- `relay-host`: carries bytes for frp deployments. It does not store jobs or queue state.
+
+The durable boundary is `clio-core`. The filesystem queue in this repository is the development backend for that record contract. Jobs, task timelines, progress, scheduler state, gateway sessions, logs, artifacts, and provenance are recorded there so clients can detach, reconnect, and replay state. JARVIS-CD owns scheduler execution, package behavior, output collection, and provenance.
+
+Transport is replaceable because it only carries HTTP bytes between endpoints:
+
+- Relay mode uses frp through a public relay host. It supports WebSocket/TLS for Cloudflare-style HTTPS infrastructure and raw TCP for environments that provide a direct public port.
+- NAT bypass uses frp XTCP to try a direct peer path between desktop and cluster. It is an optimization for lower-latency or higher-volume traffic, with fallback to relay mode and the durable queue.
+- SSH forwarding uses local port forwarding through an existing SSH or VPN path. It is useful for closed environments that do not want a public relay.
+
+Remote agent tasks, remote MCP calls, JARVIS pipelines, and gateway sessions all use the same queue and observation model. The transport can change without changing where state lives.
+
+## Install
+
+```powershell
+uv sync
+uv run clio-relay init
+uv run clio-relay install-frp
+```
+
+Add a cluster. The cluster name and agent executable are local configuration.
+
+```powershell
+uv run clio-relay cluster add --name my-cluster --ssh-host my-cluster-login --agent-adapter exec --agent-bin agent
+uv run clio-relay cluster bootstrap --cluster my-cluster
+uv run clio-relay cluster install-endpoint-service --cluster my-cluster --start --enable
+```
+
+## Submit Work
+
+Submit a JARVIS pipeline:
+
+```powershell
+uv run clio-relay job submit --cluster my-cluster --jarvis-yaml .\pipeline.yaml
+uv run clio-relay job watch <job-id> --cluster my-cluster
+uv run clio-relay job read-log <job-id> --cluster my-cluster --stream stdout
+uv run clio-relay job list-artifacts <job-id> --cluster my-cluster
+```
+
+Expose relay tools to an agent:
+
+```powershell
+uv run clio-relay agent render-mcp-config --output .\clio-relay-agent.config.toml
+uv run clio-relay agent run --cluster my-cluster --prompt /path/on/cluster/prompt.md --mcp-config /path/on/cluster/clio-relay-agent.config.toml
+```
+
+## Observe Remote Agent Work
+
+Remote agents can emit structured task timeline events while they work. This is useful when a UI needs to show discovery and planning before the final answer exists.
+
+```powershell
+uv run clio-relay job tasks <job-id> --cluster my-cluster
+uv run clio-relay job record-task-event <task-id> --cluster my-cluster --event-type dataset_found --label dataset --summary "found staged dataset" --path-ref /mnt/common/datasets/red_sea_001
+uv run clio-relay job task-events <task-id> --cluster my-cluster --cursor 1
+```
+
+The same contract is available over HTTP at `/tasks/{task_id}/events`, `/tasks/{task_id}/events/sse`, and `/tasks/{task_id}/events/ws`, and through MCP tools `relay_record_task_event` and `relay_watch_task_events`.
+
+## Manage Gateway Sessions
+
+Long-running visualization services should be tracked as durable gateway sessions. A session records the scheduler job, node, logs, published or forwarded endpoint, health metadata, and reconnect hints.
+
+```powershell
+uv run clio-relay gateway create --cluster my-cluster --name paraview-red-sea --gateway-json-file .\gateway.json
+uv run clio-relay gateway update <session-id> --cluster my-cluster --state ready --scheduler-job-id 12345 --node compute-01 --gateway-json-file .\gateway-ready.json
+uv run clio-relay gateway get <session-id> --cluster my-cluster
+uv run clio-relay gateway close <session-id> --cluster my-cluster
+```
+
+The HTTP API exposes `/gateway-sessions`, `/gateway-sessions/{session_id}`, and `/gateway-sessions/{session_id}/close`. MCP tools expose the same create, read, update, and close operations.
+
+## Choose Transport
+
+For a public relay through Cloudflare or another HTTPS edge, use frp with `transport.protocol = "wss"`:
+
+```powershell
+$env:CLIO_RELAY_FRP_TOKEN = "<shared-frp-token>"
+$env:CLIO_RELAY_STCP_SECRET = "<shared-stcp-secret>"
+uv run clio-relay cluster add --name my-cluster --ssh-host my-cluster-login --frp-server-addr relay.example.edu
+uv run clio-relay relay-host render-frpc-config --cluster my-cluster --local-port 8848
+uv run clio-relay relay-host render-frpc-visitor-config --cluster my-cluster --bind-port 8765
+uv run clio-relay relay-host test-http-transport --cluster my-cluster --local-bind-port 18765
+```
+
+For closed environments where SSH or VPN already exists, use SSH local forwarding:
+
+```powershell
+uv run clio-relay relay-host test-ssh-transport --cluster my-cluster --local-bind-port 18766 --remote-api-port 8766 --session-id relay-ssh-test
+```
+
+To leave the remote API alive for a desktop detach and later reattach:
+
+```powershell
+uv run clio-relay session start --cluster my-cluster --session-id desktop-session --remote-api-port 8766 --replace
+uv run clio-relay session status --cluster my-cluster --session-id desktop-session
+uv run clio-relay session teardown --cluster my-cluster --session-id desktop-session
+```
+
+Use `session teardown --stop-worker` only when the user chooses to clean up the persistent remote worker too.
+
+## Documentation
+
+- [architecture](docs/architecture.md)
+- [operations](docs/operations.md)
+- [release](docs/release.md)
+- [brand prompt](docs/brand.md)
+- [ai context](docs/ai/README.md)
+
+## Development
+
+```powershell
+uv run ruff check --fix
+uv run ruff format
+uv run pyright
+uv run pytest
+```
+
+The GitHub workflow runs lint, type checks, tests, package builds, and artifact validation. Publishing to PyPI is configured through trusted publishing for the `iowarp/clio-relay` repository.

clio_relay-0.9.0/README.md

@@ -0,0 +1,134 @@
+<p align="center">
+  <img src="docs/assets/clio-relay-banner.png" alt="clio-relay banner">
+</p>
+
+<h1 align="center">clio-relay</h1>
+
+`clio-relay` lets a desktop tool submit work to a remote cluster, follow it while it runs, and collect logs, artifacts, progress, and provenance without putting job state in the network tunnel.
+
+It is a piece of the federation layer for [`clio-agent`](https://github.com/iowarp/clio-agent): a local CLIO experience can delegate work to a remote machine, keep observing it, detach, reconnect, and clean up after itself. The project is also designed for use outside CLIO. Any client that can call the CLI, HTTP API, or MCP tools can use the same relay model.
+
+## How It Works
+
+`clio-relay` has three long-running roles:
+
+- `desktop`: submits work and exposes CLI, HTTP, and MCP surfaces for local tools.
+- `worker`: runs on a configured cluster, leases work, invokes JARVIS-CD, and records results.
+- `relay-host`: carries bytes for frp deployments. It does not store jobs or queue state.
+
+The durable boundary is `clio-core`. The filesystem queue in this repository is the development backend for that record contract. Jobs, task timelines, progress, scheduler state, gateway sessions, logs, artifacts, and provenance are recorded there so clients can detach, reconnect, and replay state. JARVIS-CD owns scheduler execution, package behavior, output collection, and provenance.
+
+Transport is replaceable because it only carries HTTP bytes between endpoints:
+
+- Relay mode uses frp through a public relay host. It supports WebSocket/TLS for Cloudflare-style HTTPS infrastructure and raw TCP for environments that provide a direct public port.
+- NAT bypass uses frp XTCP to try a direct peer path between desktop and cluster. It is an optimization for lower-latency or higher-volume traffic, with fallback to relay mode and the durable queue.
+- SSH forwarding uses local port forwarding through an existing SSH or VPN path. It is useful for closed environments that do not want a public relay.
+
+Remote agent tasks, remote MCP calls, JARVIS pipelines, and gateway sessions all use the same queue and observation model. The transport can change without changing where state lives.
+
+## Install
+
+```powershell
+uv sync
+uv run clio-relay init
+uv run clio-relay install-frp
+```
+
+Add a cluster. The cluster name and agent executable are local configuration.
+
+```powershell
+uv run clio-relay cluster add --name my-cluster --ssh-host my-cluster-login --agent-adapter exec --agent-bin agent
+uv run clio-relay cluster bootstrap --cluster my-cluster
+uv run clio-relay cluster install-endpoint-service --cluster my-cluster --start --enable
+```
+
+## Submit Work
+
+Submit a JARVIS pipeline:
+
+```powershell
+uv run clio-relay job submit --cluster my-cluster --jarvis-yaml .\pipeline.yaml
+uv run clio-relay job watch <job-id> --cluster my-cluster
+uv run clio-relay job read-log <job-id> --cluster my-cluster --stream stdout
+uv run clio-relay job list-artifacts <job-id> --cluster my-cluster
+```
+
+Expose relay tools to an agent:
+
+```powershell
+uv run clio-relay agent render-mcp-config --output .\clio-relay-agent.config.toml
+uv run clio-relay agent run --cluster my-cluster --prompt /path/on/cluster/prompt.md --mcp-config /path/on/cluster/clio-relay-agent.config.toml
+```
+
+## Observe Remote Agent Work
+
+Remote agents can emit structured task timeline events while they work. This is useful when a UI needs to show discovery and planning before the final answer exists.
+
+```powershell
+uv run clio-relay job tasks <job-id> --cluster my-cluster
+uv run clio-relay job record-task-event <task-id> --cluster my-cluster --event-type dataset_found --label dataset --summary "found staged dataset" --path-ref /mnt/common/datasets/red_sea_001
+uv run clio-relay job task-events <task-id> --cluster my-cluster --cursor 1
+```
+
+The same contract is available over HTTP at `/tasks/{task_id}/events`, `/tasks/{task_id}/events/sse`, and `/tasks/{task_id}/events/ws`, and through MCP tools `relay_record_task_event` and `relay_watch_task_events`.
+
+## Manage Gateway Sessions
+
+Long-running visualization services should be tracked as durable gateway sessions. A session records the scheduler job, node, logs, published or forwarded endpoint, health metadata, and reconnect hints.
+
+```powershell
+uv run clio-relay gateway create --cluster my-cluster --name paraview-red-sea --gateway-json-file .\gateway.json
+uv run clio-relay gateway update <session-id> --cluster my-cluster --state ready --scheduler-job-id 12345 --node compute-01 --gateway-json-file .\gateway-ready.json
+uv run clio-relay gateway get <session-id> --cluster my-cluster
+uv run clio-relay gateway close <session-id> --cluster my-cluster
+```
+
+The HTTP API exposes `/gateway-sessions`, `/gateway-sessions/{session_id}`, and `/gateway-sessions/{session_id}/close`. MCP tools expose the same create, read, update, and close operations.
+
+## Choose Transport
+
+For a public relay through Cloudflare or another HTTPS edge, use frp with `transport.protocol = "wss"`:
+
+```powershell
+$env:CLIO_RELAY_FRP_TOKEN = "<shared-frp-token>"
+$env:CLIO_RELAY_STCP_SECRET = "<shared-stcp-secret>"
+uv run clio-relay cluster add --name my-cluster --ssh-host my-cluster-login --frp-server-addr relay.example.edu
+uv run clio-relay relay-host render-frpc-config --cluster my-cluster --local-port 8848
+uv run clio-relay relay-host render-frpc-visitor-config --cluster my-cluster --bind-port 8765
+uv run clio-relay relay-host test-http-transport --cluster my-cluster --local-bind-port 18765
+```
+
+For closed environments where SSH or VPN already exists, use SSH local forwarding:
+
+```powershell
+uv run clio-relay relay-host test-ssh-transport --cluster my-cluster --local-bind-port 18766 --remote-api-port 8766 --session-id relay-ssh-test
+```
+
+To leave the remote API alive for a desktop detach and later reattach:
+
+```powershell
+uv run clio-relay session start --cluster my-cluster --session-id desktop-session --remote-api-port 8766 --replace
+uv run clio-relay session status --cluster my-cluster --session-id desktop-session
+uv run clio-relay session teardown --cluster my-cluster --session-id desktop-session
+```
+
+Use `session teardown --stop-worker` only when the user chooses to clean up the persistent remote worker too.
+
+## Documentation
+
+- [architecture](docs/architecture.md)
+- [operations](docs/operations.md)
+- [release](docs/release.md)
+- [brand prompt](docs/brand.md)
+- [ai context](docs/ai/README.md)
+
+## Development
+
+```powershell
+uv run ruff check --fix
+uv run ruff format
+uv run pyright
+uv run pytest
+```
+
+The GitHub workflow runs lint, type checks, tests, package builds, and artifact validation. Publishing to PyPI is configured through trusted publishing for the `iowarp/clio-relay` repository.

clio_relay-0.9.0/docs/ai/README.md

@@ -0,0 +1,14 @@
+# AI Context
+
+These files are for coding agents and review agents. Human-facing docs should stay short and readable.
+
+Read in this order:
+
+1. `system-context.md`
+2. `testing-context.md`
+3. `interface-context.md`
+4. `../../README.md`
+5. `../architecture.md`
+6. `../operations.md`
+
+Do not treat examples as hardcoded product semantics. Examples show one configured target or workload.

clio_relay-0.9.0/jarvis-packages/clio_relay/clio_relay/__init__.py

@@ -0,0 +1 @@
+"""JARVIS-CD package repository for clio-relay."""

clio_relay-0.9.0/jarvis-packages/clio_relay/clio_relay/bounded_command/__init__.py

@@ -0,0 +1 @@
+"""Bounded command JARVIS package."""

clio_relay-0.9.0/jarvis-packages/clio_relay/clio_relay/bounded_command/pkg.py

@@ -0,0 +1,169 @@
+"""JARVIS-CD package for bounded relay commands."""
+
+from __future__ import annotations
+
+import os
+import queue
+import signal
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from jarvis_cd.core.pkg import Application
+
+from clio_relay.bounded_command.progress import adapter_from_config, append_progress_record
+
+PROGRESS_FILE_ENV = "CLIO_RELAY_PROGRESS_FILE"
+PROGRESS_TOKEN_ENV = "CLIO_RELAY_PROGRESS_TOKEN"
+
+
+class BoundedCommand(Application):
+    """Execute a bounded command and let JARVIS-CD capture provenance."""
+
+    def _init(self) -> None:
+        """Initialize package state."""
+
+    def _configure_menu(self) -> list[dict[str, Any]]:
+        """Return JARVIS configurator options."""
+        return []
+
+    def _configure(self, **kwargs: Any) -> None:
+        """Store configuration provided by the pipeline YAML."""
+        self.config.update(kwargs)
+
+    def start(self) -> None:
+        """Run the configured command."""
+        command = self.config.get("command")
+        if not isinstance(command, list) or not all(isinstance(item, str) for item in command):
+            raise ValueError("command must be a string array")
+        env = os.environ.copy()
+        supplied_env = self.config.get("env", {})
+        if isinstance(supplied_env, dict):
+            env.update({str(key): str(value) for key, value in supplied_env.items()})
+        env.pop(PROGRESS_FILE_ENV, None)
+        env.pop(PROGRESS_TOKEN_ENV, None)
+        workdir_value = self.config.get("workdir")
+        workdir = Path(workdir_value) if isinstance(workdir_value, str) else None
+        timeout_value = self.config.get("timeout_seconds")
+        timeout = int(timeout_value) if timeout_value is not None else None
+        result = _run_streaming(
+            command,
+            cwd=workdir,
+            env=env,
+            timeout=timeout,
+            progress_config=self.config.get("progress"),
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"command failed with exit code {result.returncode}")
+
+    def stop(self) -> None:
+        """Stop hook for bounded commands."""
+
+    def clean(self) -> None:
+        """Clean hook for bounded commands."""
+
+
+def _run_streaming(
+    command: list[str],
+    *,
+    cwd: Path | None,
+    env: dict[str, str],
+    timeout: int | None,
+    progress_config: object,
+) -> subprocess.CompletedProcess[str]:
+    adapter = adapter_from_config(progress_config)
+    process = subprocess.Popen(
+        command,
+        cwd=cwd,
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        start_new_session=os.name != "nt",
+        creationflags=subprocess.CREATE_NEW_PROCESS_GROUP if os.name == "nt" else 0,
+    )
+    stdout_chunks: list[str] = []
+    stderr_chunks: list[str] = []
+    output_queue: queue.Queue[tuple[str, str | None]] = queue.Queue()
+
+    def read_stream(name: str, stream: Any) -> None:
+        try:
+            for line in stream:
+                output_queue.put((name, line))
+        finally:
+            output_queue.put((name, None))
+
+    assert process.stdout is not None
+    assert process.stderr is not None
+    threads = [
+        threading.Thread(target=read_stream, args=("stdout", process.stdout), daemon=True),
+        threading.Thread(target=read_stream, args=("stderr", process.stderr), daemon=True),
+    ]
+    for thread in threads:
+        thread.start()
+    deadline = None if timeout is None else time.monotonic() + timeout
+    closed_streams: set[str] = set()
+    try:
+        while len(closed_streams) < 2:
+            if deadline is not None and time.monotonic() >= deadline:
+                raise subprocess.TimeoutExpired(command, timeout)
+            try:
+                stream_name, line = output_queue.get(timeout=0.1)
+            except queue.Empty:
+                if process.poll() is not None and all(not thread.is_alive() for thread in threads):
+                    break
+                continue
+            if line is None:
+                closed_streams.add(stream_name)
+                continue
+            if stream_name == "stdout":
+                stdout_chunks.append(line)
+                print(line, end="", flush=True)
+                if adapter is not None:
+                    for record in adapter.observe_stdout(line):
+                        append_progress_record(record)
+            else:
+                stderr_chunks.append(line)
+                print(line, end="", file=sys.stderr, flush=True)
+        returncode = process.wait(timeout=1)
+    except subprocess.TimeoutExpired:
+        _terminate_process_tree(process)
+        stdout, stderr = process.communicate()
+        stdout_chunks.append(stdout)
+        stderr_chunks.append(stderr)
+        raise
+    return subprocess.CompletedProcess(
+        command,
+        returncode,
+        stdout="".join(stdout_chunks),
+        stderr="".join(stderr_chunks),
+    )
+
+
+def _terminate_process_tree(process: subprocess.Popen[str]) -> None:
+    if process.poll() is not None:
+        return
+    if os.name == "nt":
+        process.send_signal(signal.CTRL_BREAK_EVENT)
+        try:
+            process.wait(timeout=5)
+            return
+        except subprocess.TimeoutExpired:
+            process.kill()
+            return
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    try:
+        process.wait(timeout=10)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            return

clio_relay-0.9.0/jarvis-packages/clio_relay/clio_relay/bounded_command/progress.py

@@ -0,0 +1,134 @@
+"""Generic progress adapters for bounded command JARVIS packages."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+PROGRESS_FILE_ENV = "CLIO_RELAY_PROGRESS_FILE"
+PROGRESS_TOKEN_ENV = "CLIO_RELAY_PROGRESS_TOKEN"
+PACKAGE_NAME = "clio_relay.bounded_command"
+
+
+class ProgressAdapter(Protocol):
+    """Observe application output and emit structured progress records."""
+
+    def observe_stdout(self, line: str) -> list[dict[str, object]]:
+        """Return zero or more progress records derived from one stdout line."""
+        ...
+
+
+@dataclass
+class GenericRegexProgressAdapter:
+    """Extract progress from stdout using caller-supplied regular expressions."""
+
+    pattern: re.Pattern[str]
+    label: str = "progress"
+    unit: str | None = None
+    current_group: str = "current"
+    total_group: str | None = None
+    message_group: str | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    def observe_stdout(self, line: str) -> list[dict[str, object]]:
+        """Extract all matching progress observations from a stdout line."""
+        records: list[dict[str, object]] = []
+        for match in self.pattern.finditer(line):
+            current = _group_float(match, self.current_group)
+            total = _group_float(match, self.total_group) if self.total_group else None
+            message = _group_text(match, self.message_group) if self.message_group else None
+            records.append(
+                _drop_none(
+                    {
+                        "label": self.label,
+                        "current": current,
+                        "total": total,
+                        "unit": self.unit,
+                        "message": message,
+                        "metadata": {
+                            **_metadata(config=None, metadata=self.metadata),
+                            "source": "jarvis_package",
+                            "package_name": PACKAGE_NAME,
+                            "package_version": "builtin",
+                            "adapter": "regex",
+                        },
+                    }
+                )
+            )
+        return records
+
+
+def adapter_from_config(config: object) -> ProgressAdapter | None:
+    """Build a progress adapter from bounded command package configuration."""
+    if config is None:
+        return None
+    if not isinstance(config, dict):
+        raise ValueError("progress must be an object")
+    adapter = str(config.get("adapter", "regex"))
+    if adapter == "none":
+        return None
+    if adapter == "regex":
+        pattern = config.get("pattern")
+        if not isinstance(pattern, str) or pattern == "":
+            raise ValueError("regex progress adapter requires pattern")
+        return GenericRegexProgressAdapter(
+            pattern=re.compile(pattern),
+            label=str(config.get("label", "progress")),
+            unit=_optional_str(config.get("unit")),
+            current_group=str(config.get("current_group", "current")),
+            total_group=_optional_str(config.get("total_group")),
+            message_group=_optional_str(config.get("message_group")),
+            metadata=_metadata(config),
+        )
+    raise ValueError(f"unsupported progress adapter: {adapter}")
+
+
+def append_progress_record(record: dict[str, object]) -> None:
+    """Append a trusted package progress record to the relay side-channel file."""
+    path_value = os.getenv(PROGRESS_FILE_ENV)
+    token = os.getenv(PROGRESS_TOKEN_ENV)
+    if path_value is None or path_value == "" or token is None or token == "":
+        return
+    metadata = record.get("metadata")
+    if not isinstance(metadata, dict):
+        metadata = {}
+    record = {**record, "metadata": {**metadata, "relay_progress_token": token}}
+    path = Path(path_value)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record, sort_keys=True))
+        handle.write("\n")
+
+
+def _group_text(match: re.Match[str], group: str | None) -> str | None:
+    if group is None:
+        return None
+    return match.group(int(group)) if group.isdigit() else match.group(group)
+
+
+def _group_float(match: re.Match[str], group: str) -> float:
+    return float(_group_text(match, group))
+
+
+def _optional_str(value: object) -> str | None:
+    return value if isinstance(value, str) and value != "" else None
+
+
+def _metadata(
+    config: dict[str, object] | None = None,
+    *,
+    metadata: object | None = None,
+) -> dict[str, object]:
+    value = config.get("metadata", {}) if config is not None else metadata
+    if not isinstance(value, dict):
+        return {}
+    protected = {"source", "package_name", "package_version", "run_id", "execution_id", "adapter"}
+    return {str(key): item for key, item in value.items() if str(key) not in protected}
+
+
+def _drop_none(value: dict[str, object | None]) -> dict[str, object]:
+    return {key: item for key, item in value.items() if item is not None}

clio_relay-0.9.0/jarvis-packages/clio_relay/clio_relay/mcp_call/__init__.py

@@ -0,0 +1 @@
+"""MCP call JARVIS package."""