web3skill 0.1.0

package/dist/skills/web3-native-operator/references/WATCH_HEARTBEAT_TEMPLATE.md

@@ -0,0 +1,31 @@
+# Watch Heartbeat Template
+
+Use this template when a `watch_status` should be persisted into `HEARTBEAT.md`
+for later heartbeat execution.
+
+```text
+- [ ] Watch token:PEPE
+  Task: Re-run whale-watcher for token:PEPE on heartbeat and summarize any new evidence. Escalate immediately if severity becomes high or critical.
+  Watch Kind: research
+  Status: ACTIVE
+  Severity: medium
+  Adapter: whale-watcher
+  Schedule Hint: */15 * * * *
+  Next Check Hint: refresh whale flow after 15 minutes
+```
+
+## Required Fields
+
+- title line with checklist marker
+- `Task`
+- `Watch Kind`
+- `Status`
+- `Severity`
+- `Adapter`
+- `Schedule Hint`
+- `Next Check Hint`
+
+## Notes
+
+- Keep it human-readable because `HEARTBEAT.md` is consumed by the LLM, not a strict parser.
+- `Schedule Hint` stays advisory until a runtime or user turns it into a real cron job.

package/dist/skills/web3-native-operator/scripts/apply_followup_bundle_to_heartbeat.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""Apply a watch/posttrade follow-up bundle into HEARTBEAT.md."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+DEFAULT_HEARTBEAT_TEMPLATE = """# Heartbeat Tasks
+
+This file is checked every 30 minutes by your nanobot agent.
+Add tasks below that you want the agent to work on periodically.
+
+If this file has no tasks (only headers and comments), the agent will skip the heartbeat.
+
+## Active Tasks
+
+<!-- Add your periodic tasks below this line -->
+
+
+## Completed
+
+<!-- Move completed tasks here or delete them -->
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Apply a follow-up bundle to HEARTBEAT.md.")
+    parser.add_argument("--heartbeat-file", required=True)
+    parser.add_argument("--bundle-file", required=True, help="JSON file path or '-' for stdin")
+    parser.add_argument("--allow-duplicate", action="store_true")
+    return parser
+
+
+def load_payload(bundle_file: str) -> dict[str, object]:
+    if bundle_file == "-":
+        return json.load(sys.stdin)
+    return json.loads(Path(bundle_file).read_text(encoding="utf-8"))
+
+
+def extract_heartbeat_task(payload: dict[str, object]) -> tuple[str, str]:
+    for key in ("watch_followup_bundle", "posttrade_followup_bundle"):
+        bundle = payload.get(key)
+        if isinstance(bundle, dict):
+            task = bundle.get("heartbeat_task")
+            if isinstance(task, str) and task.strip():
+                return key, task.strip("\n")
+    raise ValueError("bundle does not contain a heartbeat_task")
+
+
+def ensure_template(path: Path) -> str:
+    if path.exists():
+        return path.read_text(encoding="utf-8")
+    return DEFAULT_HEARTBEAT_TEMPLATE
+
+
+def find_section_indexes(lines: list[str]) -> tuple[int, int]:
+    try:
+        active_idx = lines.index("## Active Tasks")
+        completed_idx = lines.index("## Completed")
+    except ValueError as exc:
+        raise ValueError("HEARTBEAT.md missing required section headers") from exc
+    if completed_idx <= active_idx:
+        raise ValueError("HEARTBEAT.md sections are out of order")
+    return active_idx, completed_idx
+
+
+def insert_task(content: str, task: str, allow_duplicate: bool) -> tuple[str, str, str]:
+    lines = content.splitlines()
+    active_idx, completed_idx = find_section_indexes(lines)
+    title = task.splitlines()[0].strip()
+    active_lines = lines[active_idx + 1 : completed_idx]
+    if not allow_duplicate and any(line.strip() == title for line in active_lines):
+        return content, "unchanged", title
+
+    prefix = lines[:completed_idx]
+    suffix = lines[completed_idx:]
+    while prefix and prefix[-1] == "":
+        prefix.pop()
+    while suffix and suffix[0] == "":
+        suffix.pop(0)
+
+    new_lines = prefix + [""] + task.splitlines() + [""] + suffix
+    return "\n".join(new_lines) + "\n", "updated", title
+
+
+def apply_payload_to_heartbeat_file(
+    payload: dict[str, object],
+    heartbeat_file: str | Path,
+    allow_duplicate: bool = False,
+) -> dict[str, object]:
+    heartbeat_path = Path(heartbeat_file)
+    bundle_kind, task = extract_heartbeat_task(payload)
+    content = ensure_template(heartbeat_path)
+    updated_content, status, title = insert_task(content, task, allow_duplicate)
+    heartbeat_path.write_text(updated_content, encoding="utf-8")
+    return {
+        "status": status,
+        "bundle_kind": bundle_kind,
+        "heartbeat_file": str(heartbeat_path),
+        "task_title": title,
+    }
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    payload = load_payload(args.bundle_file)
+    result = apply_payload_to_heartbeat_file(payload, args.heartbeat_file, args.allow_duplicate)
+    json.dump(result, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/skills/web3-native-operator/scripts/render_execution_bundle.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""Render a stable Web3 operator bundle from normalized risk/simulation states."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+RISK_GATE_SCRIPTS_DIR = (
+    Path(__file__).resolve().parents[2] / "web3-risk-gate" / "scripts"
+)
+if str(RISK_GATE_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(RISK_GATE_SCRIPTS_DIR))
+
+from merge_risk_gate_blocks import load_payload, merge_payloads
+
+SIMULATION_SCRIPTS_DIR = (
+    Path(__file__).resolve().parents[2] / "web3-transaction-simulator" / "scripts"
+)
+if str(SIMULATION_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SIMULATION_SCRIPTS_DIR))
+
+from merge_simulation_blocks import load_payload as load_simulation_payload
+from merge_simulation_blocks import merge_payloads as merge_simulation_payloads
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Render a Web3 operator execution bundle.")
+    parser.add_argument("--intent", required=True)
+    parser.add_argument("--chain", required=True)
+    parser.add_argument("--risk-decision", choices=("ALLOW", "WARN", "BLOCK"))
+    parser.add_argument("--risk-coverage", choices=("complete", "partial", "missing"))
+    parser.add_argument("--risk-input-file", action="append", default=[])
+    parser.add_argument(
+        "--simulation-status",
+        choices=("PASS", "WARN", "FAIL", "NO_SIMULATION"),
+    )
+    parser.add_argument(
+        "--simulation-readiness",
+        choices=("ready", "needs-confirmation", "blocked"),
+    )
+    parser.add_argument("--simulation-venue")
+    parser.add_argument("--simulation-input-file", action="append", default=[])
+    parser.add_argument("--reason", action="append", default=[])
+    parser.add_argument("--follow-up-skill", action="append", default=[])
+    return parser
+
+
+def resolve_risk_gate(
+    risk_decision: str | None,
+    risk_coverage: str | None,
+    risk_input_files: list[str],
+) -> tuple[str, str, dict[str, object] | None]:
+    if risk_input_files:
+        merged_gate = merge_payloads([load_payload(path) for path in risk_input_files])["risk_gate"]
+        merged_decision = str(merged_gate["decision"])
+        merged_coverage = str(merged_gate["coverage"])
+        if risk_decision and risk_decision != merged_decision:
+            raise ValueError(
+                f"explicit risk decision {risk_decision} conflicts with merged risk_gate {merged_decision}"
+            )
+        if risk_coverage and risk_coverage != merged_coverage:
+            raise ValueError(
+                f"explicit risk coverage {risk_coverage} conflicts with merged risk_gate {merged_coverage}"
+            )
+        return merged_decision, merged_coverage, merged_gate
+
+    if not risk_decision:
+        raise ValueError("risk decision is required unless --risk-input-file is provided")
+    return risk_decision, risk_coverage or "complete", None
+
+
+def resolve_simulation(
+    simulation_status: str | None,
+    simulation_readiness: str | None,
+    simulation_venue: str | None,
+    simulation_input_files: list[str],
+) -> tuple[str, str, str, dict[str, object] | None]:
+    if simulation_input_files:
+        merged_simulation = merge_simulation_payloads(
+            [load_simulation_payload(path) for path in simulation_input_files]
+        )["simulation"]
+        merged_status = str(merged_simulation["status"])
+        merged_readiness = str(merged_simulation["readiness"])
+        merged_venue = str(merged_simulation.get("venue", ""))
+        if simulation_status and simulation_status != merged_status:
+            raise ValueError(
+                f"explicit simulation status {simulation_status} conflicts with merged simulation {merged_status}"
+            )
+        if simulation_readiness and simulation_readiness != merged_readiness:
+            raise ValueError(
+                "explicit simulation readiness "
+                f"{simulation_readiness} conflicts with merged simulation {merged_readiness}"
+            )
+        if simulation_venue and merged_venue and simulation_venue != merged_venue:
+            raise ValueError(
+                f"explicit simulation venue {simulation_venue} conflicts with merged simulation {merged_venue}"
+            )
+        return merged_status, merged_readiness, simulation_venue or merged_venue, merged_simulation
+
+    if not simulation_status:
+        raise ValueError("simulation status is required unless --simulation-input-file is provided")
+    return (
+        simulation_status,
+        simulation_readiness or "needs-confirmation",
+        simulation_venue or "",
+        None,
+    )
+
+
+def validate_merged_context(
+    intent: str,
+    chain: str,
+    merged_gate: dict[str, object] | None,
+    merged_simulation: dict[str, object] | None,
+) -> None:
+    if merged_gate is not None:
+        gate_action = str(merged_gate.get("action", ""))
+        gate_chain = str(merged_gate.get("chain", ""))
+        if gate_action and gate_action != intent:
+            raise ValueError(f"risk_gate action {gate_action} conflicts with intent {intent}")
+        if gate_chain and gate_chain != chain:
+            raise ValueError(f"risk_gate chain {gate_chain} conflicts with chain {chain}")
+
+    if merged_simulation is not None:
+        simulation_action = str(merged_simulation.get("action", ""))
+        simulation_chain = str(merged_simulation.get("chain", ""))
+        if simulation_action and simulation_action != intent:
+            raise ValueError(f"simulation action {simulation_action} conflicts with intent {intent}")
+        if simulation_chain and simulation_chain != chain:
+            raise ValueError(f"simulation chain {simulation_chain} conflicts with chain {chain}")
+
+
+def choose_state(
+    risk_decision: str,
+    risk_coverage: str,
+    simulation_status: str,
+    simulation_readiness: str,
+) -> tuple[str, str, bool]:
+    if risk_decision == "BLOCK" or simulation_status == "FAIL":
+        return "blocked", "stop", False
+    if simulation_status == "NO_SIMULATION" or risk_coverage != "complete":
+        return "investigate-more", "investigate", False
+    if (
+        risk_decision == "WARN"
+        or simulation_status == "WARN"
+        or simulation_readiness == "needs-confirmation"
+    ):
+        return "needs-confirmation", "confirm_then_route", True
+    return "ready-to-route", "route", False
+
+
+def choose_route(
+    state: str,
+    intent: str,
+    venue: str,
+    follow_up_skills: list[str],
+) -> str:
+    if state == "blocked":
+        return "none"
+    if state == "investigate-more":
+        return follow_up_skills[0] if follow_up_skills else "web3-trace-and-state-analysis"
+    if venue == "hyperliquid":
+        return "hyperliquid"
+    if intent == "liquidity":
+        return "liquidity-planner"
+    if venue == "token-swap" or intent == "swap":
+        return "token-swap"
+    return "web3-native-operator"
+
+
+def build_execution_bundle(
+    intent: str,
+    chain: str,
+    risk_decision: str,
+    risk_coverage: str,
+    simulation_status: str,
+    simulation_readiness: str,
+    simulation_venue: str,
+    reasons: list[str],
+    follow_up_skills: list[str],
+) -> dict[str, object]:
+    state, execution_mode, requires_confirmation = choose_state(
+        risk_decision,
+        risk_coverage,
+        simulation_status,
+        simulation_readiness,
+    )
+    return {
+        "version": 1,
+        "workflow_kind": "execution",
+        "intent": intent,
+        "chain": chain,
+        "state": state,
+        "next_adapter": choose_route(
+            state,
+            intent,
+            simulation_venue,
+            follow_up_skills,
+        ),
+        "execution_mode": execution_mode,
+        "requires_user_confirmation": requires_confirmation,
+        "inputs": {
+            "risk_decision": risk_decision,
+            "risk_coverage": risk_coverage,
+            "simulation_status": simulation_status,
+            "simulation_readiness": simulation_readiness,
+            "simulation_venue": simulation_venue,
+        },
+        "follow_up_skills": follow_up_skills,
+        "reasons": reasons,
+    }
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        risk_decision, risk_coverage, merged_gate = resolve_risk_gate(
+            args.risk_decision,
+            args.risk_coverage,
+            args.risk_input_file,
+        )
+        simulation_status, simulation_readiness, simulation_venue, merged_simulation = resolve_simulation(
+            args.simulation_status,
+            args.simulation_readiness,
+            args.simulation_venue,
+            args.simulation_input_file,
+        )
+        validate_merged_context(args.intent, args.chain, merged_gate, merged_simulation)
+    except ValueError as exc:
+        parser.error(str(exc))
+    payload: dict[str, object] = {
+        "operator_bundle": build_execution_bundle(
+            intent=args.intent,
+            chain=args.chain,
+            risk_decision=risk_decision,
+            risk_coverage=risk_coverage,
+            simulation_status=simulation_status,
+            simulation_readiness=simulation_readiness,
+            simulation_venue=simulation_venue,
+            reasons=args.reason,
+            follow_up_skills=args.follow_up_skill,
+        )
+    }
+    if merged_gate is not None:
+        payload["risk_gate"] = merged_gate
+    if merged_simulation is not None:
+        payload["simulation"] = merged_simulation
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())