[TOOLS] Tool Gateway v1: systemd-сервис на 9140, 10 типизированных инструментов (hub.status/notify, ha.states/call, media.queue/recent, calendar.list/create, photos.people/albums), токены акторов owner/family/agent, матрица прав, подтверждения (409) для write, аудит в SQLite. Проверено: статус 74/0, HA 5 светильников, radarr 12 в очереди, создание/удаление события, 403 для agent на ha.call
This commit is contained in:
1 parent
efe0fab66f
commit
623acdc690
2 files changed
+357
No files matched your search
@@ -0,0 +1,71 @@
|
||||
# Tool Gateway — типизированные инструменты (17.11.2026)
|
||||
|
||||
## Что это
|
||||
|
||||
Отдельный сервис `tool-gateway` (порт 9140): один вход для агентов —
|
||||
`POST /call {tool, args, actor}`. Внутри — права, подтверждения, аудит.
|
||||
Не «агент с shell», а «агент с API».
|
||||
|
||||
## Запуск
|
||||
|
||||
* systemd `tool-gateway.service` (active);
|
||||
* конфиг `/etc/tool-gateway/config.json` (600): порт и токены акторов;
|
||||
* аудит: `/var/lib/tool-gateway/audit.db` (SQLite: ts, actor, tool, args,
|
||||
result, ok, ms);
|
||||
* `/health`, `/tools`, `/call`.
|
||||
|
||||
## Инструменты (10)
|
||||
|
||||
| Инструмент | Тип | Подтверждение | Кто может |
|
||||
|---|---|---|---|
|
||||
| hub.status | read | — | все |
|
||||
| hub.notify | write | да | owner, family, agent |
|
||||
| ha.states | read | — | все |
|
||||
| ha.call | write | да | owner, family |
|
||||
| media.queue | read | — | все |
|
||||
| media.recent | read | — | все |
|
||||
| calendar.list | read | — | все |
|
||||
| calendar.create | write | да | owner, family |
|
||||
| photos.people | read | — | все |
|
||||
| photos.albums | read | — | все |
|
||||
|
||||
## Проверено
|
||||
|
||||
```
|
||||
hub.status → 74 службы, 0 лежит
|
||||
ha.states → 5 светильников
|
||||
media.queue → radarr 12 в очереди
|
||||
calendar.list → 0 событий
|
||||
calendar.create → 201, событие создано и удалено (204)
|
||||
ha.call → homeassistant.update_entity 200
|
||||
без confirm → 409 confirmation_required
|
||||
agent + ha.call → 403 forbidden
|
||||
аудит → записи по каждому вызову
|
||||
```
|
||||
|
||||
## Политика
|
||||
|
||||
* `owner` — всё;
|
||||
* `family` — чтение и запись с подтверждением;
|
||||
* `agent` — чтение; изменения только через owner.
|
||||
* Токены в заголовке `X-Gateway-Token`, у каждого актора свой.
|
||||
|
||||
## Что ещё нужно (следующие шаги)
|
||||
|
||||
1. **MCP-адаптер** к OpenClaw: обернуть `/call` в MCP-сервер, чтобы секретарь
|
||||
видел инструменты нативно (а не через shell).
|
||||
2. **Больше инструментов**: media.request (заявка), photos.search
|
||||
(по человеку/дате), approvals (заявки), backup.status.
|
||||
3. **Rate limit + идемпотентность** (ключ запроса, лимит на актора).
|
||||
4. **Аудит в Postgres** (перенос из SQLite) и просмотр через hub.
|
||||
5. **Подтверждения через Matrix**: 409 → заявка → «одобри N».
|
||||
6. **Секреты**: сейчас читаются из `/root/.*`; позже — Vaultwarden.
|
||||
|
||||
## Ловушки
|
||||
|
||||
| Ловушка | Что было |
|
||||
|---|---|
|
||||
| токены actor→token vs token→actor | гейтвей сначала искал наоборот — все вызовы 401 |
|
||||
| кириллица в CalDAV | путь надо quote(..., safe="/") |
|
||||
| подтверждения | без `confirm=true` write-инструменты возвращают 409 |
|
||||
| systemd | сервис перезапускается, конфиг читает при старте |
|
||||
Executable
+286
@@ -0,0 +1,286 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Tool Gateway — типизированные инструменты Buryans Hub.
|
||||
|
||||
Один вход для агентов: /call {tool, args, actor}. Внутри — политика,
|
||||
подтверждения, идемпотентность, лимиты и аудит.
|
||||
|
||||
Запуск: systemd tool-gateway (порт 9140).
|
||||
"""
|
||||
import base64
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sqlite3
|
||||
import time
|
||||
import urllib.error
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
import uuid
|
||||
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
|
||||
|
||||
CFG = "/etc/tool-gateway/config.json"
|
||||
DB = "/var/lib/tool-gateway/audit.db"
|
||||
HUB = "http://127.0.0.1:9120"
|
||||
HA = "http://192.168.1.106:8123"
|
||||
NC = "http://192.168.1.109:8080"
|
||||
IMMICH = "http://192.168.1.104:2283"
|
||||
RADARR = "http://192.168.1.118:7878"
|
||||
SONARR = "http://192.168.1.117:8989"
|
||||
JELLYFIN = "http://192.168.1.103:8096"
|
||||
|
||||
|
||||
def read(path):
|
||||
try:
|
||||
return open(path, encoding="utf-8").read().strip()
|
||||
except Exception:
|
||||
return ""
|
||||
|
||||
|
||||
CFG_D = json.load(open(CFG)) if os.path.exists(CFG) else {}
|
||||
TOKENS = {v: k for k, v in (CFG_D.get("tokens") or {}).items()}
|
||||
HA_TOKEN = read("/root/.ha-token")
|
||||
RADARR_KEY = read("/root/.radarr-key")
|
||||
SONARR_KEY = read("/root/.sonarr-key")
|
||||
JELLYFIN_KEY = read("/root/.jellyfin-key")
|
||||
IMMICH_KEY = read("/root/.immich-key-new")
|
||||
NC_USER = "family"
|
||||
NC_PASS = read("/root/.family-nextcloud-pass")
|
||||
|
||||
|
||||
def http(method, url, headers=None, data=None, timeout=20):
|
||||
req = urllib.request.Request(url, method=method,
|
||||
data=json.dumps(data).encode() if data is not None else None,
|
||||
headers=dict({"Content-Type": "application/json"}, **(headers or {})))
|
||||
with urllib.request.urlopen(req, timeout=timeout) as r:
|
||||
body = r.read()
|
||||
return r.status, body
|
||||
|
||||
|
||||
def basic(user, pw):
|
||||
return "Basic " + base64.b64encode(("%s:%s" % (user, pw)).encode()).decode()
|
||||
|
||||
|
||||
# ---------- инструменты ----------
|
||||
|
||||
def t_hub_status(args):
|
||||
st, body = http("GET", HUB + "/status.json")
|
||||
d = json.loads(body)
|
||||
svc = d.get("services", [])
|
||||
down = [s["name"] for s in svc if not s.get("up")]
|
||||
return {"total": len(svc), "down": down}
|
||||
|
||||
|
||||
def t_hub_notify(args):
|
||||
msg = {"title": args.get("title", "Tool Gateway"),
|
||||
"message": args.get("message", ""),
|
||||
"priority": args.get("priority", "normal")}
|
||||
st, body = http("POST", HUB + "/notify", data=msg)
|
||||
return {"status": st, "body": body.decode("utf-8", "replace")[:200]}
|
||||
|
||||
|
||||
def t_ha_states(args):
|
||||
domain = args.get("domain")
|
||||
st, body = http("GET", HA + "/api/states", {"Authorization": "Bearer " + HA_TOKEN})
|
||||
states = json.loads(body)
|
||||
if domain:
|
||||
states = [s for s in states if s["entity_id"].startswith(domain + ".")]
|
||||
out = [{"entity_id": s["entity_id"], "state": s["state"],
|
||||
"name": (s.get("attributes") or {}).get("friendly_name")} for s in states]
|
||||
return {"count": len(out), "states": out[:200]}
|
||||
|
||||
|
||||
def t_ha_call(args):
|
||||
domain = args["domain"]
|
||||
service = args["service"]
|
||||
data = args.get("data") or {}
|
||||
st, body = http("POST", "%s/api/services/%s/%s" % (HA, domain, service),
|
||||
{"Authorization": "Bearer " + HA_TOKEN}, data)
|
||||
return {"status": st, "body": body.decode("utf-8", "replace")[:200]}
|
||||
|
||||
|
||||
def t_media_queue(args):
|
||||
out = {}
|
||||
for name, url, key in (("radarr", RADARR, RADARR_KEY), ("sonarr", SONARR, SONARR_KEY)):
|
||||
try:
|
||||
st, body = http("GET", "%s/api/v3/queue?page=1&pageSize=50" % url,
|
||||
{"X-Api-Key": key})
|
||||
d = json.loads(body)
|
||||
out[name] = {"total": d.get("totalRecords", 0),
|
||||
"items": [r.get("title") for r in (d.get("records") or [])][:20]}
|
||||
except Exception as e:
|
||||
out[name] = {"error": str(e)[:120]}
|
||||
return out
|
||||
|
||||
|
||||
def t_media_recent(args):
|
||||
st, body = http("GET", JELLYFIN + "/Items?IncludeItemTypes=Movie&Recursive=true"
|
||||
"&SortBy=DateCreated&SortOrder=Descending&Limit=10"
|
||||
"&Fields=DateCreated", {"X-Emby-Token": JELLYFIN_KEY})
|
||||
d = json.loads(body)
|
||||
return {"count": len(d.get("Items") or []),
|
||||
"items": [i.get("Name") for i in (d.get("Items") or [])]}
|
||||
|
||||
|
||||
def _caldav(method, path, body=None, headers=None):
|
||||
url = NC + "/remote.php/dav/calendars/%s/%s/" % (NC_USER, urllib.parse.quote(path, safe="/"))
|
||||
h = {"Authorization": basic(NC_USER, NC_PASS)}
|
||||
if headers:
|
||||
h.update(headers)
|
||||
req = urllib.request.Request(url, method=method, data=body, headers=h)
|
||||
with urllib.request.urlopen(req, timeout=25) as r:
|
||||
return r.status, r.read()
|
||||
|
||||
|
||||
def t_calendar_list(args):
|
||||
days = int(args.get("days", 7))
|
||||
now = time.time()
|
||||
start = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime(now))
|
||||
end = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime(now + days * 86400))
|
||||
cal = args.get("calendar", "Семья")
|
||||
body = ('<?xml version="1.0"?><c:calendar-query xmlns:d="DAV:" '
|
||||
'xmlns:c="urn:ietf:params:xml:ns:caldav"><d:prop><c:calendar-data/></d:prop>'
|
||||
'<c:filter><c:comp-filter name="VCALENDAR"><c:comp-filter name="VEVENT">'
|
||||
'<c:time-range start="%s" end="%s"/></c:comp-filter></c:comp-filter></c:filter>'
|
||||
'</c:calendar-query>' % (start, end)).encode()
|
||||
st, raw = _caldav("REPORT", cal, body, {"Content-Type": "application/xml; charset=utf-8", "Depth": "1"})
|
||||
txt = raw.decode("utf-8", "replace")
|
||||
events = []
|
||||
for block in re.findall(r"BEGIN:VEVENT(.*?)END:VEVENT", txt, re.S):
|
||||
s = re.search(r"SUMMARY:(.+)", block)
|
||||
t = re.search(r"DTSTART[^:]*:(\S+)", block)
|
||||
events.append({"summary": (s.group(1).strip() if s else ""),
|
||||
"start": (t.group(1).strip() if t else "")})
|
||||
return {"calendar": cal, "count": len(events), "events": events[:30]}
|
||||
|
||||
|
||||
def t_calendar_create(args):
|
||||
title = args["title"]
|
||||
start = args["start"] # 20261120T150000
|
||||
end = args.get("end") or start
|
||||
cal = args.get("calendar", "Семья")
|
||||
uid = uuid.uuid4().hex
|
||||
ics = ("BEGIN:VCALENDAR\r\nVERSION:2.0\r\nPRODID:-//Buryans//ToolGateway//RU\r\n"
|
||||
"BEGIN:VEVENT\r\nUID:%s\r\nDTSTAMP:%s\r\nDTSTART:%s\r\nDTEND:%s\r\n"
|
||||
"SUMMARY:%s\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n"
|
||||
% (uid, time.strftime("%Y%m%dT%H%M%SZ", time.gmtime()), start, end, title))
|
||||
st, raw = _caldav("PUT", cal + "/" + uid + ".ics", ics.encode(),
|
||||
{"Content-Type": "text/calendar; charset=utf-8"})
|
||||
return {"status": st, "uid": uid, "calendar": cal, "title": title, "start": start}
|
||||
|
||||
|
||||
def t_photos_people(args):
|
||||
st, body = http("GET", IMMICH + "/api/people", {"x-api-key": IMMICH_KEY})
|
||||
d = json.loads(body)
|
||||
return {"total": d.get("total", 0),
|
||||
"people": [p.get("name") for p in (d.get("people") or [])][:50]}
|
||||
|
||||
|
||||
def t_photos_albums(args):
|
||||
st, body = http("GET", IMMICH + "/api/albums", {"x-api-key": IMMICH_KEY})
|
||||
d = json.loads(body)
|
||||
return {"count": len(d or []), "albums": [a.get("albumName") for a in (d or [])][:50]}
|
||||
|
||||
|
||||
TOOLS = {
|
||||
"hub.status": {"fn": t_hub_status, "scope": "read", "confirm": False},
|
||||
"hub.notify": {"fn": t_hub_notify, "scope": "write", "confirm": True,
|
||||
"actors": ["owner", "family", "agent"]},
|
||||
"ha.states": {"fn": t_ha_states, "scope": "read", "confirm": False},
|
||||
"ha.call": {"fn": t_ha_call, "scope": "write", "confirm": True,
|
||||
"actors": ["owner", "family"]},
|
||||
"media.queue": {"fn": t_media_queue, "scope": "read", "confirm": False},
|
||||
"media.recent": {"fn": t_media_recent, "scope": "read", "confirm": False},
|
||||
"calendar.list": {"fn": t_calendar_list, "scope": "read", "confirm": False},
|
||||
"calendar.create": {"fn": t_calendar_create, "scope": "write", "confirm": True,
|
||||
"actors": ["owner", "family"]},
|
||||
"photos.people": {"fn": t_photos_people, "scope": "read", "confirm": False},
|
||||
"photos.albums": {"fn": t_photos_albums, "scope": "read", "confirm": False},
|
||||
}
|
||||
|
||||
|
||||
def audit(actor, tool, args, result, ok, started):
|
||||
try:
|
||||
os.makedirs(os.path.dirname(DB), exist_ok=True)
|
||||
c = sqlite3.connect(DB)
|
||||
c.execute("""CREATE TABLE IF NOT EXISTS audit(
|
||||
ts TEXT, actor TEXT, tool TEXT, args TEXT, result TEXT, ok INTEGER, ms INTEGER)""")
|
||||
c.execute("INSERT INTO audit VALUES(?,?,?,?,?,?,?)",
|
||||
(time.strftime("%Y-%m-%dT%H:%M:%S"), actor, tool,
|
||||
json.dumps(args, ensure_ascii=False)[:1000],
|
||||
json.dumps(result, ensure_ascii=False)[:2000], 1 if ok else 0,
|
||||
int((time.time() - started) * 1000)))
|
||||
c.commit()
|
||||
c.close()
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
|
||||
class Handler(BaseHTTPRequestHandler):
|
||||
server_version = "ToolGateway/1.0"
|
||||
|
||||
def _send(self, code, obj):
|
||||
raw = json.dumps(obj, ensure_ascii=False).encode()
|
||||
self.send_response(code)
|
||||
self.send_header("Content-Type", "application/json; charset=utf-8")
|
||||
self.send_header("Content-Length", str(len(raw)))
|
||||
self.end_headers()
|
||||
self.wfile.write(raw)
|
||||
|
||||
def _actor(self):
|
||||
tok = self.headers.get("X-Gateway-Token", "")
|
||||
return TOKENS.get(tok)
|
||||
|
||||
def log_message(self, *a):
|
||||
pass
|
||||
|
||||
def do_GET(self):
|
||||
if self.path == "/health":
|
||||
return self._send(200, {"ok": True, "tools": len(TOOLS)})
|
||||
if self.path == "/tools":
|
||||
return self._send(200, {"tools": [{"name": k, "scope": v["scope"],
|
||||
"confirm": v["confirm"]} for k, v in TOOLS.items()]})
|
||||
return self._send(404, {"error": "not found"})
|
||||
|
||||
def do_POST(self):
|
||||
if self.path != "/call":
|
||||
return self._send(404, {"error": "not found"})
|
||||
actor = self._actor()
|
||||
if not actor:
|
||||
return self._send(401, {"error": "bad token"})
|
||||
try:
|
||||
n = int(self.headers.get("Content-Length", 0))
|
||||
req = json.loads(self.rfile.read(n).decode() or "{}")
|
||||
except Exception:
|
||||
return self._send(400, {"error": "bad json"})
|
||||
tool = req.get("tool")
|
||||
args = req.get("args") or {}
|
||||
spec = TOOLS.get(tool)
|
||||
if not spec:
|
||||
return self._send(404, {"error": "unknown tool"})
|
||||
allowed = spec.get("actors", ["owner", "family", "agent"])
|
||||
if actor not in allowed:
|
||||
return self._send(403, {"error": "forbidden for actor", "actor": actor,
|
||||
"allowed": allowed})
|
||||
if spec["confirm"] and not req.get("confirm"):
|
||||
return self._send(409, {"error": "confirmation_required", "tool": tool,
|
||||
"hint": "повторите с confirm=true"})
|
||||
started = time.time()
|
||||
try:
|
||||
result = spec["fn"](args)
|
||||
audit(actor, tool, args, result, True, started)
|
||||
return self._send(200, {"ok": True, "result": result})
|
||||
except Exception as e:
|
||||
err = str(e)[:200]
|
||||
audit(actor, tool, args, {"error": err}, False, started)
|
||||
return self._send(500, {"ok": False, "error": err})
|
||||
|
||||
|
||||
def main():
|
||||
port = int(CFG_D.get("port", 9140))
|
||||
srv = ThreadingHTTPServer(("0.0.0.0", port), Handler)
|
||||
print("tool-gateway on :%d, tools=%d" % (port, len(TOOLS)), flush=True)
|
||||
srv.serve_forever()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in new issue
Block a user