@runweave/server-linux-x64 0.1.8 → 0.1.10

package/payload/plugins/toolkit/skills/suiji/scripts/work_records.py

@@ -0,0 +1,328 @@
+"""Work-fact commands. Authentication and frozen-write transport stay in suiji.py."""
+import datetime as dt
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import tempfile
+import uuid
+
+STATUSES = {"progress", "discussed", "documented", "attempted", "agent-reported", "verified"}
+FIELDS = {"workDate", "title", "statement", "status", "project"}
+
+
+def validate(payload, fail, enforce_limits=True):
+    def require(ok, message):
+        if not ok:
+            raise fail(message)
+    def exact(value, keys, optional=()):
+        require(isinstance(value, dict) and not set(value) - set(keys) - set(optional) and set(keys) <= set(value), "INVALID_WORK_FIELDS")
+    def text(value, maximum, blank=False):
+        require(isinstance(value, str) and len(value) <= maximum and (blank or bool(value.strip())), "INVALID_WORK_TEXT")
+        require(all(not (ord(c) < 32 and c not in "\t\r\n") and not 127 <= ord(c) <= 159 and not 0xD800 <= ord(c) <= 0xDFFF for c in value), "INVALID_WORK_UNICODE")
+    def identity(value):
+        text(value, 240)
+        require(not value.startswith(("/", "~")) and not re.match(r"^[A-Za-z]:[\\/]", value) and not any(c in value for c in "\r\n\t"), "INVALID_STABLE_KEY")
+    def scope(value):
+        require(isinstance(value, str) and bool(re.fullmatch(r"[A-Za-z0-9_.:-]{1,120}", value)), "INVALID_SOURCE_SCOPE")
+    def timestamp(value):
+        require(isinstance(value, str) and bool(re.fullmatch(r"\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)", value)), "INVALID_SOURCE_TIME")
+        return dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
+    exact(payload, {"schemaVersion", "sourceNamespace", "sourceCollectedAt", "days"}, {"basedOnFeedRevision", "materialResults"})
+    require(payload["schemaVersion"] == 1, "INVALID_WORK_SCHEMA")
+    scope(payload["sourceNamespace"])
+    if "basedOnFeedRevision" in payload:
+        require(bool(re.fullmatch(r"0|[1-9][0-9]{0,18}", payload["basedOnFeedRevision"])), "INVALID_FEED_REVISION")
+    require(isinstance(payload["days"], list) and 1 <= len(payload["days"]) <= 100, "INVALID_WORK_DAYS")
+    results = payload.get("materialResults", [])
+    require(isinstance(results, list) and (not enforce_limits or len(results) <= 100), "INVALID_MATERIAL_RESULTS")
+    seen = set()
+    for item in results:
+        exact(item, {"recordId", "recordVersion", "sourceHash", "outcome", "eventKeys"})
+        uuid.UUID(item["recordId"])
+        require(item["recordId"] not in seen and type(item["recordVersion"]) is int and item["recordVersion"] > 0, "INVALID_MATERIAL_VERSION")
+        seen.add(item["recordId"])
+        require(bool(re.fullmatch(r"[a-f0-9]{64}", item["sourceHash"])), "INVALID_MATERIAL_HASH")
+        require(item["outcome"] in {"included", "merged", "no-new-fact"} and isinstance(item["eventKeys"], list) and len(item["eventKeys"]) <= 100, "INVALID_MATERIAL_OUTCOME")
+        require(bool(item["eventKeys"]) == (item["outcome"] != "no-new-fact"), "MATERIAL_EVENT_KEYS_REQUIRED")
+        for key in item["eventKeys"]:
+            identity(key)
+    dates, keys, times, count = set(), set(), [], 0
+    for day in payload["days"]:
+        exact(day, {"date", "requestedScopes", "receipts", "facts"})
+        date = dt.date.fromisoformat(day["date"])
+        require(date.isoformat() == day["date"] and day["date"] not in dates, "INVALID_WORK_DATE")
+        dates.add(day["date"])
+        requested = day["requestedScopes"]
+        require(isinstance(requested, list) and 1 <= len(requested) <= 100 and len(set(requested)) == len(requested), "INVALID_REQUESTED_SCOPES")
+        for s in requested:
+            scope(s)
+        receipts = {}
+        require(isinstance(day["receipts"], list), "INVALID_RECEIPTS")
+        for receipt in day["receipts"]:
+            exact(receipt, {"sourceScope", "status", "collectedAt", "from", "to"})
+            s = receipt["sourceScope"]
+            require(s in requested and s not in receipts and receipt["status"] in {"complete", "partial", "unavailable"}, "INVALID_RECEIPT_SCOPE")
+            start = dt.datetime.combine(date, dt.time(), dt.timezone(dt.timedelta(hours=8)))
+            require(timestamp(receipt["from"]) == start and timestamp(receipt["to"]) == start + dt.timedelta(days=1), "INVALID_RECEIPT_WINDOW")
+            times.append(timestamp(receipt["collectedAt"]))
+            receipts[s] = receipt
+        require(set(receipts) == set(requested), "MISSING_SOURCE_RECEIPT")
+        require(isinstance(day["facts"], list), "INVALID_FACTS")
+        for fact in day["facts"]:
+            exact(fact, {"externalKey", "eventKey", "title", "statement", "status", "project", "sourceRefs"})
+            for k in ("externalKey", "eventKey"):
+                identity(fact[k])
+            require(fact["externalKey"] not in keys, "DUPLICATE_EXTERNAL_KEY")
+            keys.add(fact["externalKey"])
+            require(isinstance(fact["title"], str), "INVALID_WORK_TITLE")
+            fact["title"] = fact["title"].strip()
+            text(fact["title"], 80)
+            require(not any(c in fact["title"] for c in "\n\r\t"), "INVALID_TITLE")
+            text(fact["statement"], 4000)
+            require(fact["status"] in STATUSES, "INVALID_WORK_STATUS")
+            if fact["project"] is not None:
+                require(isinstance(fact["project"], str), "INVALID_PROJECT")
+                fact["project"] = fact["project"].strip() or None
+                if fact["project"] is not None:
+                    text(fact["project"], 80)
+                    require(not any(c in fact["project"] for c in "\n\r\t"), "INVALID_PROJECT")
+            require(isinstance(fact["sourceRefs"], list) and 1 <= len(fact["sourceRefs"]) <= 100, "SOURCE_REQUIRED")
+            if all(ref["channel"] == "screen-timeline" for ref in fact["sourceRefs"]):
+                require(fact["status"] in {"documented", "discussed"}, "SCREEN_ONLY_IS_OBSERVATION")
+            for ref in fact["sourceRefs"]:
+                exact(ref, {"channel", "sourceScope", "nativeId"}, {"revision", "hash"})
+                require(ref["channel"] in {"local-agent", "feishu-message", "feishu-document", "browser-visit", "screen-timeline", "suiji-material"} and ref["sourceScope"] in receipts and receipts[ref["sourceScope"]]["status"] != "unavailable", "SOURCE_NOT_READ")
+                for field in ("nativeId", "revision"):
+                    if field in ref:
+                        identity(ref[field])
+                        require(not any(c in ref[field] for c in "/\\") and "://" not in ref[field], "NATIVE_ID_REQUIRED")
+                require("hash" not in ref or bool(re.fullmatch(r"[a-fA-F0-9]{64}", ref["hash"])), "INVALID_SOURCE_HASH")
+            count += 1
+    require(timestamp(payload["sourceCollectedAt"]) == max(times), "SOURCE_TIME_MUST_MATCH_RECEIPTS")
+    require(not enforce_limits or (count <= 100 and len(json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode()) <= 200 * 1024), "WORK_PACKAGE_LIMIT: split whole days; prepare the next only after receipt confirmation")
+    return payload
+
+
+def list_all(client, filters, fail):
+    items, days, cursor, revision = [], {}, None, None
+    while True:
+        page = client.call("list_work_facts", {**filters, **({"cursor": cursor} if cursor else {})})
+        if revision is not None and page["feedRevision"] != revision:
+            raise fail("WORK_FEED_CHANGED; discard this incomplete read and restart")
+        revision = page["feedRevision"]
+        items.extend(page["items"])
+        days.update({day["date"]: day for day in page["days"]})
+        next_cursor = page.get("nextCursor")
+        if not next_cursor:
+            return {"items": items, "days": sorted(days.values(), key=lambda d: d["date"], reverse=True), "nextCursor": None, "feedRevision": revision}
+        if next_cursor == cursor:
+            raise fail("INVALID_PAGINATION; incomplete read")
+        cursor = next_cursor
+
+
+def identity_key(namespace, external):
+    return json.dumps([namespace, external], ensure_ascii=False, separators=(",", ":"))
+
+
+def index_path(args):
+    return Path(args.config).with_suffix(".work-identities.json")
+
+
+def atomic_private(path, data):
+    fd, temporary = tempfile.mkstemp(prefix=".work-index-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "wb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def prepare(client, args, fail, private_read, exclusive_write):
+    payload = validate(json.loads(private_read(args.input)), fail, enforce_limits=False)
+    original = payload
+    material_dates = {}
+    for item in payload.get("materialResults", []):
+        record = client.call("get_record", {"recordId": item["recordId"]})["record"]
+        if not record.get("material") or record["material"]["sourceHash"] != item["sourceHash"] or record["version"] != item["recordVersion"]:
+            raise fail("MATERIAL_VERSION_CHANGED")
+        material_dates[item["recordId"]] = record["material"]["materialDate"]
+    def select_materials(value):
+        if "materialResults" in value:
+            dates = {d["date"] for d in value["days"]}
+            value["materialResults"] = [r for r in original["materialResults"] if material_dates[r["recordId"]] in dates]
+        return value
+    kept = []
+    for day in original["days"]:
+        trial = select_materials({**original, "days": kept + [day]})
+        trial["sourceCollectedAt"] = max((r["collectedAt"] for d in trial["days"] for r in d["receipts"]), key=lambda v: dt.datetime.fromisoformat(v.replace("Z", "+00:00")))
+        if len(trial.get("materialResults", [])) > 100 or sum(len(d["facts"]) for d in trial["days"]) > 100 or len(json.dumps(trial, ensure_ascii=False, separators=(",", ":")).encode()) > 200 * 1024:
+            if not kept:
+                raise fail("SINGLE_DAY_PACKAGE_LIMIT; refuse to truncate a day")
+            break
+        kept.append(day)
+    payload = {**original, "days": kept, "sourceCollectedAt": max((r["collectedAt"] for d in kept for r in d["receipts"]), key=lambda v: dt.datetime.fromisoformat(v.replace("Z", "+00:00")))}
+    payload = select_materials(payload)
+    remaining = original["days"][len(kept):]
+    validate(payload, fail)
+    page = list_all(client, {}, fail)
+    if payload.get("basedOnFeedRevision") not in (None, page["feedRevision"]):
+        raise fail("WORK_FEED_CHANGED; review the current facts before preparing again")
+    payload["basedOnFeedRevision"] = page["feedRevision"]
+    identity = {"endpoint": client.base, "serverId": client.config["serverId"], "ownerId": client.config["ownerId"]}
+    path = index_path(args)
+    index = json.loads(private_read(path)) if path.exists() else {"identity": identity, "keys": {}}
+    if index["identity"] != identity:
+        raise fail("INDEX_IDENTITY_MISMATCH")
+    previews = []
+    by_id = {f["id"]: f for f in page["items"]}
+    for day in payload["days"]:
+        for f in day["facts"]:
+            key = identity_key(payload["sourceNamespace"], f["externalKey"])
+            old = index["keys"].get(key)
+            if old is None and index.get("schemaVersion", 1) == 1:
+                old = index["keys"].get(payload["sourceNamespace"] + ":" + f["externalKey"])
+            if old and old["eventKey"] != f["eventKey"]:
+                raise fail("STABLE_EVENT_IDENTITY_CHANGED")
+            index["keys"][key] = {**(old or {}), "eventKey": f["eventKey"], "sourceNamespace": payload["sourceNamespace"], "externalKey": f["externalKey"]}
+            current = by_id.get((old or {}).get("id"))
+            previews.append({"date": day["date"], "externalKey": f["externalKey"], "title": f["title"], "status": f["status"], "manualFields": current["manualFields"] if current else [], "current": current})
+    atomic_private(path, json.dumps(index, ensure_ascii=False).encode())
+    out = Path(args.out)
+    out.mkdir(mode=0o700, parents=True, exist_ok=False)
+    frozen = {"identity": identity, "payload": payload, "indexPath": str(path.resolve())}
+    if remaining:
+        remainder = {k: v for k, v in original.items() if k != "basedOnFeedRevision"}
+        remainder["days"] = remaining
+        select_materials(remainder)
+        remainder["sourceCollectedAt"] = max((r["collectedAt"] for d in remaining for r in d["receipts"]), key=lambda v: dt.datetime.fromisoformat(v.replace("Z", "+00:00")))
+        exclusive_write(out / "remaining.json", json.dumps(remainder, ensure_ascii=False).encode())
+    exclusive_write(out / "prepared.json", json.dumps(frozen, ensure_ascii=False).encode())
+    exclusive_write(out / "preview.json", json.dumps({"feedRevision": page["feedRevision"], "facts": previews, "days": [{"date": d["date"], "count": len(d["facts"]), "receipts": d["receipts"]} for d in payload["days"]]}, ensure_ascii=False, indent=2).encode())
+    return {"prepared": str(out / "prepared.json"), "preview": str(out / "preview.json"), "facts": len(previews), "feedRevision": page["feedRevision"], "writes": 0, "remainingDays": len(remaining), "next": "Only after confirming this receipt, prepare remaining.json" if remaining else None}
+
+
+def verify_result(client, intent, result, fail):
+    operation, args = intent["operation"], intent["arguments"]
+    if operation == "import_work_facts":
+        inputs = {f["externalKey"]: {**f, "workDate": d["date"]} for d in args["input"]["days"] for f in d["facts"]}
+        facts = result.get("facts", [])
+        if not result.get("importId") or len(facts) != len(inputs) or len({r["externalKey"] for r in facts}) != len(inputs):
+            raise fail("INVALID_IMPORT_RECEIPT; original request retained")
+        if sum(result.get(k, -1) for k in ("created", "updated", "unchanged")) != len(inputs):
+            raise fail("INVALID_IMPORT_COUNTS; original request retained")
+        for row in facts:
+            expected = inputs.get(row["externalKey"])
+            actual = row["fact"]
+            if not expected or actual["id"] != row["id"] or actual["eventKey"] != expected["eventKey"] or actual["version"] != row["version"]:
+                raise fail("INVALID_IMPORT_FACT_RECEIPT")
+            if any(actual[field] != expected[field] for field in FIELDS - set(actual["manualFields"])):
+                raise fail("IMPORT_EFFECTIVE_FIELDS_MISMATCH")
+            current = client.call("get_work_fact", {"factId": row["id"]})["fact"]
+            if current != actual:
+                if current.get("id") != actual["id"] or current.get("eventKey") != actual["eventKey"] or current.get("version", 0) <= actual["version"]:
+                    raise fail("IMPORT_READBACK_MISMATCH; original request retained")
+                result.setdefault("changedSinceReceipt", []).append(row["id"])
+        for item in args["input"].get("materialResults", []):
+            receipt = client.call("get_material_result", {"recordId": item["recordId"], "recordVersion": item["recordVersion"]})
+            if receipt.get("sourceHash") != item["sourceHash"] or not receipt.get("processedAt"):
+                raise fail("MATERIAL_READBACK_MISMATCH; original request retained")
+    elif operation == "reclassify_work_facts":
+        facts = result.get("facts", [])
+        expected = {i["id"]: i for i in args["input"]["items"]}
+        if {f["id"] for f in facts} != set(expected) or any(f["project"] != expected[f["id"]].get("project", args["input"].get("project")) or f["version"] != expected[f["id"]]["expectedVersion"] + 1 for f in facts):
+            raise fail("INVALID_RECLASSIFICATION_RECEIPT")
+        for fact in facts:
+            if client.call("get_work_fact", {"factId": fact["id"]})["fact"] != fact:
+                raise fail("RECLASSIFICATION_READBACK_CHANGED")
+    return result
+
+
+def reclassification(value, fail):
+    if not isinstance(value, dict) or set(value) not in ({"items", "project"}, {"items"}):
+        raise fail("INVALID_RECLASSIFICATION_FIELDS")
+    if not isinstance(value["items"], list) or not 1 <= len(value["items"]) <= 100:
+        raise fail("INVALID_RECLASSIFICATION_COUNT")
+    def project(value):
+        if value is None:
+            return None
+        if not isinstance(value, str):
+            raise fail("INVALID_PROJECT")
+        result = value.strip() or None
+        if result is not None and (len(result) > 80 or any(ord(c) < 32 or 127 <= ord(c) <= 159 or 0xD800 <= ord(c) <= 0xDFFF for c in result)):
+            raise fail("INVALID_PROJECT")
+        return result
+    seen = set()
+    for item in value["items"]:
+        fields = {"id", "expectedVersion"} | ({"project"} if "project" not in value else set())
+        if not isinstance(item, dict) or set(item) != fields:
+            raise fail("INVALID_RECLASSIFICATION_ITEM")
+        if not isinstance(item["id"], str):
+            raise fail("INVALID_FACT_ID")
+        uuid.UUID(item["id"])
+        if item["id"] in seen or type(item["expectedVersion"]) is not int or item["expectedVersion"] < 1:
+            raise fail("INVALID_RECLASSIFICATION_VERSION_OR_DUPLICATE")
+        seen.add(item["id"])
+        if "project" in item:
+            item["project"] = project(item["project"])
+    if "project" in value:
+        value["project"] = project(value["project"])
+    return value
+
+
+def recovery_intent(args, config, fail, private_read):
+    """Opt-in automation is restricted to an already frozen work import."""
+    job = json.loads(private_read(args.job_config))
+    intent = json.loads(private_read(args.request))
+    if job.get("suiji", {}).get("autoPublish") is not True:
+        raise fail("AUTO_PUBLISH_DISABLED")
+    if Path(job["suiji"]["configPath"]).resolve() != Path(args.config).resolve():
+        raise fail("JOB_CONNECTION_MISMATCH")
+    if intent.get("operation") != "import_work_facts":
+        raise fail("WORK_IMPORT_ONLY")
+    expected = {k: config[k] for k in ("serverId", "ownerId")}
+    # endpoint normalization is done by the shared client before any write.
+    if any(intent.get("identity", {}).get(k) != v for k, v in expected.items()):
+        raise fail("REQUEST_IDENTITY_MISMATCH")
+    payload = intent["arguments"]["input"]
+    if payload.get("sourceNamespace") != job.get("sourceNamespace"):
+        raise fail("JOB_SOURCE_MISMATCH")
+    validate(payload, fail)
+    local = job["sources"]["localAgent"]["providers"]
+    allowed = {"agent:" + job["producerId"] + ":" + p for p in local}
+    if job["sources"]["feishu"]["enabled"]:
+        allowed.add("feishu:" + job["sources"]["feishu"]["accountScope"] + ":messages")
+    browser = job["sources"].get("browser", {})
+    screen = job["sources"].get("screen", {})
+    materials = job["sources"].get("materials", {})
+    for day in payload["days"]:
+        expected = set(allowed)
+        if browser.get("enabled") and day["date"] >= browser["effectiveFrom"]:
+            expected.add("browser:" + job["producerId"] + ":observed")
+        if screen.get("enabled") and day["date"] >= screen["effectiveFrom"]:
+            expected.add("screen:" + job["producerId"] + ":" + screen["expectedDeviceID"] + ":observed")
+        if materials.get("enabled") and day["date"] >= materials["effectiveFrom"]:
+            expected.add("materials:" + materials["accountScope"])
+        if set(day["requestedScopes"]) != expected:
+            raise fail("JOB_SCOPE_MISMATCH")
+    return intent
+
+
+def reconcile(client, request, intent, fail, run_intent):
+    import time
+    for attempt in range(3):
+        try:
+            return run_intent(client, request, intent)
+        except fail as error:
+            # Explicit feed conflicts are terminal rejections, never unknown writes.
+            if not any(str(error).startswith(code) for code in
+                       ("NETWORK_RESULT_UNKNOWN", "DEPENDENCY_UNAVAILABLE", "HTTP_502", "HTTP_503", "HTTP_504")):
+                raise
+            if attempt == 2:
+                raise
+            time.sleep(attempt + 1)

package/payload/plugins/toolkit/skills/suiji/scripts/work_reports.py

@@ -0,0 +1,75 @@
+"""Prepare a seven-calendar-day report from the authoritative Suiji work feed."""
+import datetime as dt
+import json
+from pathlib import Path
+import time
+
+import work_records
+
+SHANGHAI = dt.timezone(dt.timedelta(hours=8))
+
+
+def period(anchor=None, now=None):
+    today = (now or dt.datetime.now(SHANGHAI)).astimezone(SHANGHAI).date()
+    friday = dt.date.fromisoformat(anchor) if anchor else today - dt.timedelta(days=(today.weekday() - 4) % 7)
+    if friday.weekday() != 4 or friday > today:
+        raise ValueError("ANCHOR_MUST_BE_A_PAST_OR_CURRENT_FRIDAY")
+    return {"from": (friday - dt.timedelta(days=7)).isoformat(), "to": (friday - dt.timedelta(days=1)).isoformat()}
+
+
+def identity(client):
+    return {"endpoint": client.base, **{k: client.config[k] for k in ("serverId", "ownerId")}}
+
+
+def prepare(client, args, fail, write):
+    window = period(args.anchor)
+    deadline = time.monotonic() + int(args.wait_seconds)
+    while True:
+        feed = work_records.list_all(client, {**window, "view": "logs"}, fail)
+        incomplete = [d for d in feed["days"] if d["coverage"] != "complete"]
+        if not incomplete or time.monotonic() >= deadline:
+            break
+        time.sleep(min(30, max(0, deadline - time.monotonic())))
+    sources = client.call("list_work_sources", window)
+    existing = client.call("find_work_report", window)["report"]
+    if existing and existing["manuallyEdited"]:
+        raise fail("REPORT_MANUALLY_EDITED; preserve the existing report")
+    payload = {**window, "basedOnFeedRevision": feed["feedRevision"],
+               "sourceFacts": [{"id": f["id"], "version": f["version"]} for f in feed["items"]]}
+    if existing:
+        payload["expectedVersion"] = existing["version"]
+    value = {"identity": identity(client), "payload": payload, "facts": feed["items"],
+             "days": feed["days"], "sources": sources, "existingReport": existing,
+             "incompleteDates": [d["date"] for d in incomplete]}
+    root = Path(args.out)
+    root.mkdir(mode=0o700, parents=True, exist_ok=False)
+    target = root / "prepared.json"
+    write(target, json.dumps(value, ensure_ascii=False).encode())
+    return {"prepared": str(target), **window, "factCount": len(feed["items"]),
+            "complete": not incomplete, "incompleteDates": value["incompleteDates"],
+            "instructions": "Read every fact, merge repeated matters across days and sources. Preserve outcome evidence and unresolved work. Save title/body JSON, then report-publish. Missing sources are not zero work."}
+
+
+def publish(client, args, fail, read, write, run):
+    prepared = json.loads(read(args.input))
+    if prepared["identity"] != identity(client):
+        raise fail("PREPARED_IDENTITY_MISMATCH")
+    result = json.loads(read(args.file))
+    if set(result) != {"title", "body"} or not all(isinstance(result[k], str) and result[k].strip() for k in result):
+        raise fail("REPORT_TITLE_AND_BODY_REQUIRED")
+    import uuid
+    intent = {"identity": prepared["identity"], "operation": "publish_work_report",
+              "arguments": {"idempotencyKey": str(uuid.uuid4()), "input": {**prepared["payload"], **result}},
+              "receiptPath": str(Path(args.request).with_suffix(".receipt.json"))}
+    write(args.request, json.dumps(intent, ensure_ascii=False).encode())
+    return run(client, args.request, intent)
+
+
+def verify(client, intent, result, fail):
+    value = result.get("report", {})
+    expected = intent["arguments"]["input"]
+    if not value.get("id") or any(value.get(k) != expected[k] for k in ("from", "to", "title", "body", "sourceFacts")):
+        raise fail("INVALID_REPORT_RESPONSE; original request retained")
+    actual = client.call("get_work_report", {"reportId": value["id"]})["report"]
+    if actual != value:
+        raise fail("REPORT_READBACK_CHANGED; original request retained")

package/payload/plugins/toolkit/skills/sync-branch-hard-reset/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: sync-branch-hard-reset
+description: 当用户给出一个 Git 分支名，并要求先 fetch、切换到该分支、如有本地代码先 stash、再用 reset --hard 将该分支更新到 origin/main 最新代码，最后还原之前 stash 的本地改动时使用。
+---
+
+# 同步分支到 origin/main 最新
+
+仅当用户明确给出目标分支名，并希望把该本地分支强制同步到远程主分支 `origin/main` 的最新代码时使用。这个流程会执行 `git reset --hard`，必须严格按顺序操作。
+
+## 输入
+
+- `branch_name`：用户给出的分支名。
+- 如果用户给的是 `origin/<branch>`，本地分支名按 `<branch>` 处理，但 reset 基准仍然是 `origin/main`。
+- 默认远端是 `origin`。用户明确指定其他 remote 时，才使用其他 remote。
+
+## 固定流程
+
+1. 检查当前状态：
+   - `git status --short`
+   - `git branch --show-current`
+2. 如果 `git status --short` 有输出，先 stash 本地改动：
+   - `git stash push -u -m "before hard reset <branch_name> $(date +%Y%m%d-%H%M%S)"`
+   - 记录 `git stash list -1` 的输出，并记住最新 stash ref，例如 `stash@{0}`。
+   - 如果 stash 失败，停止，不要继续 fetch、switch 或 reset。
+3. 更新远端引用：
+   - `git fetch --prune origin`
+4. 确认远程主分支存在：
+   - `git rev-parse --verify --quiet origin/main`
+   - 如果不存在，停止，并说明 `origin/main` 不存在；不要执行 `reset --hard`。
+5. 切换到目标分支：
+   - 如果本地分支已存在：`git switch <branch_name>`
+   - 如果本地分支不存在：`git switch -c <branch_name> --no-track origin/main`
+6. 强制同步到 `origin/main` 最新：
+   - `git reset --hard origin/main`
+7. 如果第 2 步创建过 stash，还原本地改动：
+   - `git stash pop <stash_ref>`
+   - 如果还原时出现冲突，停止并报告冲突文件；不要继续做其他修复，除非用户明确要求。
+8. 验证结果：
+   - `git status --short`
+   - `git branch -vv`
+   - `git log -1 --oneline`
+
+## 边界
+
+- 不要在 stash 成功前执行 `reset --hard`。
+- 如果本流程创建了 stash，reset 完成后必须尝试 `git stash pop` 还原；不要把用户的本地改动长期留在 stash 里不处理。
+- 不要把 reset 目标改成 `origin/<branch_name>`，除非用户明确要求同步到同名远端分支。
+- 不要 push。
+- 不要删除分支。
+- 不要处理和目标分支同步无关的改动。
+
+## 回复
+
+完成后简短说明：
+
+- 当前分支。
+- 已 reset 到 `origin/main` 的哪个最新 commit。
+- 是否创建并还原了 stash；如果还原冲突，给出冲突文件和 stash 状态。
+- `git status --short` 是否为空。

package/payload/plugins/toolkit/skills/update-runweave-backend/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: update-runweave-backend
+description: 通过 npm 更新 Linux 机器上的 Runweave CLI、Backend、Web 与 App Server，检查服务、登录、任务保活和开机自启；旧源码部署先迁移到 npm。用于“升级远程机器到最新版”“更新服务器 CLI 和服务”及无桌面后台；发布 npm 新版本使用 publish-runweave-server，不用于 macOS、桌面端、手机端或 Dev Session。
+---
+
+# 更新 Runweave Linux 后台
+
+纯服务端统一使用 npm 发行包，不在服务器 git pull、编译或运行源码安装器升级。
+旧源码部署先执行一次迁移，随后进入相同的 npm 升级流程；本地 Mac 桌面端仍保留源码更新，
+由其专属流程处理。CI 从源码构建发行包，不属于目标机器的源码升级。
+
+## 范围与入口
+
+读取目标仓库的 `AGENTS.md`、`docs/deployment/npm-server-operations.md`、
+`docs/cli/server-cli.md`、`docs/cli/configuration.md` 和 `docs/cli/service-management.md`。
+服务器本身不需要源码仓库；按本技能及已安装 CLI 的帮助操作。
+涉及配置版本变化时另读仓库的 `docs/deployment/configuration-upgrades.md`；
+没有仓库时按本技能的预检边界及发行包提供的版本声明、迁移入口操作，不猜测命令。
+旧源码部署另读 `docs/deployment/backend-standalone.md` 的一次性迁移流程。
+
+每次整套更新都建立下表。状态只能是待更新、已更新、已一致、不适用或受阻，并记录依据；缺少安装不能直接记为“不适用”。
+
+程序更新状态与运行/自启状态分列。用户主动停用只说明应保留 disabled/inactive，不证明程序版本已一致；若其程序属于本次更新范围，离线更新并保留停用状态，未核对版本前不能标“已一致”。
+
+| 组件                     | 默认处理                                                                            |
+| ------------------------ | ----------------------------------------------------------------------------------- |
+| Backend 与 Web 静态资源  | 必查、一起更新；包含 Activity、Evolution、定时任务 workers 和原生依赖               |
+| App Server               | 必查、更新安装与运行进程；缺少时补齐所需配置和托管，无法补齐则报告受阻              |
+| 全局 `rw`                | 必查，更新服务用户实际使用的入口及被服务/Hook 固定引用的入口                        |
+| Research MCP、隧道       | 已部署或目标明确需要时纳入，分别检查程序、配置、运行与自启                          |
+| 飞书 Bridge              | `hub`/`standalone` 单独核对并默认保持现状，明确要求时才更新；`node` 随 Backend 更新 |
+| 快照分享、其他配套服务   | 对照实际 unit、容器、配置与进程补入，不限于固定名称                                 |
+| 随记、推送网关等独立产品 | 属于用户指定目标时纳入；同机存在也先说明归属，不因“整套后台”跨机器批量更新          |
+
+定时任务调度、Activity、Evolution 是 Backend 能力，不为它们另造 daemon。代理与隧道通常验证原配置和运行即可；不顺便升级操作系统、第三方 Agent CLI 或重新申请凭据。保留用户明确停用的服务，不借更新重新启用。
+
+## 1. 识别目标与恢复条件
+
+- 确认 Linux 主机、服务运行用户、实例、配置根、Backend profile、安装来源及目标 npm 版本。SSH 用户不等于服务用户；profile 不会把本地文件操作变成远程操作。
+- 记录已安装、active、running 版本及 sourceRevision，核对 registry 的目标精确版本和平台包。旧源码部署只记录当前基线及恢复材料，保留仓库和本地修改，不执行源码升级。
+- 查 systemd 的已安装 unit 和运行 unit，也查用户级 unit、容器及手动进程；不能只看当前活跃服务或按名字含 `runweave` 筛选。记录真实 unit、owner、ExecStart、数据路径、运行版本、启用状态和依赖。检查输出前过滤 unit/进程参数中的凭据，不打印完整环境文件或进程环境。
+- 保留原 HOME、CODEX_HOME、配置、Agent 登录态、Backend 身份、tmux socket、数据库和 Activity 正文密钥。备份配置、unit/drop-in、旧发布指针与可回退产物；运行中数据库使用其一致性备份方法，不把普通文件复制当成完整备份。
+- 检查目标 Node、架构、libc、ABI、磁盘、依赖工具和权限；Server 使用匹配目标环境的 Node 22 平台包。容器或没有 systemd 的环境沿用已有 supervisor；报告不能执行 systemd 分支，不用 `nohup` 冒充开机自启。
+- 维护通道必须能在 Backend/Bridge/MCP 停止后继续使用，例如独立 SSH。若当前 Agent 只能通过待更新服务控制主机，先建立可恢复的独立通道，再切换；不让更新切断唯一控制路径。
+
+先向用户简述目标、组件清单、目标版本、预计中断与恢复方式。已有整套更新授权时继续执行，不重复索要许可；目标机器或实例确实无法确定时才询问。
+
+## 2. 升级或迁移
+
+已由 `rw server` 管理的实例按 [NPM 机器升级](references/npm-update.md) 固定 CLI/Server 两个目标版本，
+在原 prefix 升级 CLI，再用 `rw server update --version` 升级服务。
+版本已一致且运行正常时不重新安装或重启。不重复 init、service install 或手动切换 current。
+
+旧源码或独立 Backend 包部署按仓库的 `docs/deployment/backend-standalone.md` 完成一次性迁移。
+先准备公开 npm 产物、备份和恢复条件，再停止原 owner；不对运行中的实例直接强行接管。
+缺少兼容的平台发行包时报告具体缺口，交给发布流程解决，不退回服务器源码构建。
+
+配置调整使用 `runweave-management`，保留 CAS 与敏感值私有输入。核对旧进程实际采用的
+`terminal.tmux.shutdownPolicy=preserve` 与 Backend unit 的 `KillMode=process`；
+只修改配置不能保护仍采用 cleanup 的旧进程，需先排空任务或采用已验证的迁移方式。
+
+## 3. 服务托管与配套能力
+
+按 [systemd 检查](references/systemd.md) 核对唯一 owner、身份、持久自启与恢复条件。
+新装/迁移使用 `rw server service install --dry-run` 审查生成配置，再注册；正常更新复用现有托管。
+已有容器或 supervisor 时保留其持久启动机制，进程使用已发布 npm 产物，不叠加第二套 owner。
+
+独立 Hub/MCP/隧道按实际归属核对兼容性、配置、运行与自启。未包含在 Server npm 包的独立程序，
+不假定随包更新，也不调用旧源码安装器补齐；若本次明确要求更新，使用它自己的受支持发行入口，
+缺少发行产物则报告受阻，不把单独产品的失败掩盖为整套完成。保留用户主动停用的服务。
+
+每次切换后检查实际进程与健康。异常时停止后续切换，依据实际状态修复；
+回退前检查数据/schema 与配置兼容性，不自动回滚数据库、覆盖新增数据或启动遗留 unit 抢占实例。
+
+## 4. 验证更新与开机恢复
+
+逐项取得证据，不能只看安装返回值或 `systemctl is-active`：
+
+- **版本**：实际进程的 entry、release/build ID、sourceRevision 或产物摘要对应目标基线；`command -v rw`、`rw version --json` 对应服务用户和 unit 使用的 CLI。
+- **服务**：检查目标 unit 的 MainPID、退出结果、重启次数和本轮日志；App Server owner 与 systemd MainPID 一致，Backend 能连接它。保留原身份、配置路径与数据路径。
+- **业务**：通过真实 profile 检查 `rw health`、`rw status`、项目/终端只读查询及已启用能力。状态快照不能覆盖独立服务时另行检查。浏览器交互验收使用 `playwright-cli`；没有执行就明确未验收，不能用 HTTP 200 代替 Web 可用。消息投递或向已有 Agent 输入不是默认验收动作。
+- **会话**：对比升级前后 tmux server、pane、任务 PID 和输出，确认所声明的 Backend 重启保活；定时任务同时检查排空/恢复状态，不重放业务任务来制造成功。
+- **自启配置**：逐项核对持久 enable 状态及启动依赖；用户级服务还须检查 linger。保留显式停用意图。静态 unit 须证明有持久启动依赖，`enabled-runtime` 不算跨重启生效。
+- **整机重启**：只有用户已授权重启该机器时才执行。先保存检查清单、boot ID、基线和重连方式；重连后核对 boot ID 已改变，在手动启动任何服务之前检查全部服务和业务。补启动成功只能算修复，不能算该次自动恢复通过。
+
+没有实际整机重启时报告“自启配置已检查，整机重启未验证”，不因此阻止交付已完成的更新。整机重启会终止 tmux/Agent 进程；服务自启不承诺原业务任务自动续跑，也不要配置开机自动拉取代码或再次更新来代替启动已安装版本。
+
+## 交付
+
+报告目标机器/实例、目标 npm 版本与 sourceRevision、每个组件的旧新版本、安装与运行结果、自启配置和业务验证。将“运行验证通过”“自启配置通过”“整机重启验证通过”分开，说明未覆盖项及失败后的实际状态。任一必需组件受阻时不能宣布整套完成；无需为本技能运行安装或更新其他 skill。

package/payload/plugins/toolkit/skills/update-runweave-backend/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "升级 Runweave npm 后台"
+  short_description: "升级机器的 CLI 与 Server npm 包，验证服务、登录和任务保活"
+  default_prompt: "使用 $update-runweave-backend 通过 npm 升级目标 Linux 机器的 CLI 和 Server；旧源码部署先迁移，检查服务、登录、终端保活及开机自启。"

package/payload/plugins/toolkit/skills/update-runweave-backend/references/npm-update.md

@@ -0,0 +1,68 @@
+# NPM 部署的机器升级
+
+适用于已由 `rw server` 管理的 Linux Stable。通用合同见目标仓库的 `docs/cli/server-cli.md`；
+已知机器的路径约定见 `docs/deployment/npm-server-operations.md`。使用远端已安装 CLI 时先核对帮助，
+不要求目标机器安装源码仓库。旧源码部署先按仓库 `docs/deployment/backend-standalone.md` 一次性迁移；不再提供源码日常升级。
+
+## 固定目标与恢复材料
+
+- 通过独立 SSH 在目标机器确认服务用户、HOME、Node、实例、配置根、npm prefix 和实际 rw wrapper。
+  查询 `server status --json`、`server doctor --json`、CLI 包内 package.json 与 systemd 状态。
+  CLI 的源码版本与 npm 版本可能不同，不能只看 `rw version` 判断 npm 包版本。
+- 用户说“升级后台到最新版”时，默认核对独立 CLI 和 Server 两个 npm 包。
+  用户只要求其中一个时保持范围；版本已一致且运行正常时不重新安装或重启。
+- 将目标 channel 解析成两个精确版本并记录。优先使用发布流程交接的已验证版本；
+  默认 latest，不能因为 next 编号较大就自动选 next。确认对应平台包、Node ABI 与管理协议兼容。
+- 保存配置、unit/drop-in、安装记录、发布指针、现有 npm 包版本及可恢复产物，数据库使用一致性备份。
+  对比基线包括项目/终端 ID、tmux socket/pane/任务 PID。保留密钥和 Agent 登录态，不输出凭据。
+- 向用户简述旧新版本、机器和短暂连接中断，已有升级授权时继续。服务原本停用则保持停用。
+  普通 tmux Agent 可保活，但正在调用 HTTP/WS 的操作仍可能受影响。
+
+## 升级顺序
+
+切换前先核对目标发行版的配置要求。配置结构版本、域版本与编辑 revision 不是 npm 版本；
+“最新配置”指目标程序要求的结构。候选迁移应在副本上预演并校验，备份后在受控切换阶段提交，
+业务只读取迁移后的目标结构。CLI 与旧 Server 共用配置时，不得在 CLI 更新后提前迁移共享域。
+核对所有实际配置消费者，缺少必需输入、迁移链或共同可用的切换方案时，在停服前报告受阻。
+
+`rw config migrate --source-manifest` 仅导入旧文件。新版 CLI/Server 提供版本迁移；
+先读取 `rw server status --json`，只有 `cliCapabilities.updateDryRun === true` 才执行
+`rw server update --version <目标版本> --dry-run`。旧 CLI 可能接受但忽略这个参数，
+不能用实际调用来试探是否支持预演；缺少能力字段时先升级到已验证支持它的 CLI。
+预演通过后用同一精确版本执行更新；提交时仍由 CLI 校验 CAS，不提前用 `config upgrade`
+修改运行实例。旧工具缺少入口且目标需要迁移时报告受阻，不手改版本号或现场写迁移脚本。
+数据兼容拒绝须交给发行流程处理，不跳过检查。
+
+1. CLI 若需要更新，在原 npm prefix、原服务 HOME 与 Node PATH 下安装核验过的精确版本。
+   采用该机器已验证的 sudo/用户方式；不能用 SSH 登录用户的裸 `npm install -g` 改装到另一个 prefix。
+   不覆盖实例 wrapper。读取实际包版本和 wrapper 指向，执行 CLI 帮助及 `server status` 确认管理能力可用。
+2. 只有 CLI 管理能力确认可用后，执行同一实例入口的
+   `rw server update --version <精确Server版本>`。由该命令执行下载/原生与兼容预检、维护租约、
+   停止、安装、切换、原运行模式重启与健康检查。无需重复 init、service install 或手动改 current。
+3. 若出现 `SERVER_TASKS_ACTIVE`，列明受影响执行并等待后重查；不默认 force。
+   数据不兼容、原生预检失败或安装归属不明时先解决，不停止旧服务冒险继续。
+   `--force` 不能解除数据与原生兼容限制。
+4. 安装或更新返回不确定时重新读取实际状态、包版本、发布指针和 update receipt，
+   不凭旧日志重放整套操作。CLI 成功、Server 失败要分别报告，不称整套升级成功。
+
+CLI 与 Server 的升级不是跨包/跨数据库原子事务。配置和 active 指针均未变化时，新版 CLI
+会尝试恢复原服务；已经提交配置或激活新版后不自动回滚，按回执判断实际状态。
+CLI 切换后若管理能力失效，确认恢复条件后可在原 prefix 重装保存的旧 CLI；
+Server 恢复使用兼容版本的 `server update --version`。不能自动恢复旧数据库覆盖升级后的写入，
+也不因 npm 更新失败重新启动遗留源码 unit 与新服务争抢实例。
+若配置已经迁移，旧程序启动前必须有匹配的配置恢复方案；核对备份身份、结构版本与
+升级后的配置修改，不能直接重装旧 CLI 并假定它能读新版配置。配置备份恢复不代表数据库可回退。
+
+## 真实验证与交付
+
+- CLI npm 版本、Server installed/active/running 版本对应目标，Backend/App Server PID 与 supervisor 一致。
+- 配置源/目标结构版本、执行的迁移步骤与恢复位置有据可查；发生配置变化时核对 saved/applied revision，未观测到消费者应用不能声称已生效。
+- 对本应运行的服务检查健康、重启次数、日志和持久自启；本来停用的服务检查已安装版本并保留停用状态。
+- 通过合法现有 profile 或私有凭据输入完成认证业务请求，核对项目/终端及 tmux 保活。
+  验证登录时创建的临时 session 应注销，不泄露 token 或重置用户密码。
+- 若用户报告某个入口登录失败，在那个入口复测前保持问题未解决；CLI 鉴权和健康 200 不等于用户 UI 成功。
+- 独立 Hub/MCP/隧道按原范围单独核对，不因 Server 包更新顺带重启其他产品。
+- 不默认整机重启。分别报告程序版本、运行验证、自启配置与真实重启验收，以及未完成项和恢复位置。
+
+交付应让用户看懂“哪台机器的 CLI 从什么版本到什么版本，Server 从什么版本到什么版本，
+服务与登录是否可用，现有任务是否保留”。仅需要升级机器时，不创建新的 npm 发行版。