@teevee98/synapse-hub 3.8.5 → 3.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/.agents/skills/playwright-webapp-testing/SKILL.md +6 -4
  2. package/.agents/skills/token-and-context-optimizer/SKILL.md +1 -1
  3. package/.cursor/rules/agents.mdc +1 -1
  4. package/NOTICE +48 -0
  5. package/README.en.md +2 -2
  6. package/README.md +2 -2
  7. package/agentskills.json +1 -1
  8. package/docs/ARCHITECTURE.en.md +5 -1
  9. package/docs/ARCHITECTURE.md +5 -1
  10. package/docs/CLI_REFERENCE.en.md +7 -11
  11. package/docs/CLI_REFERENCE.md +7 -11
  12. package/docs/QUALITY_GATES.en.md +5 -5
  13. package/docs/QUALITY_GATES.md +5 -5
  14. package/docs/adopted-ecosystem-tools.md +37 -0
  15. package/docs/diagrams/clean_pom.svg +48 -0
  16. package/docs/diagrams/fsm_flow.svg +78 -0
  17. package/package.json +1 -1
  18. package/plugin.json +1 -1
  19. package/scripts/install.ps1 +1 -1
  20. package/skills_manifest.json +1 -1
  21. package/synapse.config.json +1 -1
  22. package/tools/__init__.py +1 -1
  23. package/tools/browser_helpers.js +2 -2
  24. package/tools/build_consolidated_report.py +1640 -0
  25. package/tools/cli.py +3 -3
  26. package/tools/core/memory_bus.py +25 -24
  27. package/tools/core/process_supervisor.py +15 -5
  28. package/tools/dashboard_generator.py +6 -6
  29. package/tools/diagram_architect.py +220 -0
  30. package/tools/distill_log.py +31 -0
  31. package/tools/git_worktree_manager.py +185 -0
  32. package/tools/humanize_linter.py +4 -0
  33. package/tools/interview_story.py +25 -2
  34. package/tools/mcp_docx_server.py +1 -1
  35. package/tools/mcp_excel_server.py +1 -1
  36. package/tools/mcp_server.py +1 -1
  37. package/tools/mechanical_ui_gate.py +242 -0
  38. package/tools/pairwise_generator.py +175 -0
  39. package/tools/repo_map.py +1 -1
  40. package/tools/runaway_stopper.py +178 -0
  41. package/tools/ui_server.py +1 -1
  42. package/tools/update_sentinel.py +3 -3
  43. package/tools/verify_all.py +15 -0
  44. package/tools/welcome_page.py +1 -1
@@ -0,0 +1,178 @@
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """
4
+ tools/runaway_stopper.py — Agent Runaway & Token Loop Sentinel
5
+ Inspired by Garry Tan's gstack (R70/R91 runaway stopper) adapted for Synapse Hub.
6
+ Prevents runaway subagent threads, context window blowout, and infinite loops.
7
+ 100% UTF-8 No BOM.
8
+ """
9
+
10
+ import sys
11
+ import os
12
+ import json
13
+ import argparse
14
+ from typing import Dict, List, Any, Optional
15
+
16
+ # Enforce UTF-8 stdout encoding
17
+ if hasattr(sys.stdout, "reconfigure"):
18
+ try:
19
+ sys.stdout.reconfigure(encoding="utf-8")
20
+ sys.stderr.reconfigure(encoding="utf-8")
21
+ except Exception:
22
+ pass
23
+
24
+ DEFAULT_THRESHOLDS = {
25
+ "max_turns": 30,
26
+ "warn_turns": 20,
27
+ "max_tokens": 150000,
28
+ "warn_tokens": 100000,
29
+ "max_repeated_calls": 3,
30
+ "empty_turn_threshold": 4,
31
+ }
32
+
33
+ class RunawaySentinel:
34
+ def __init__(self, thresholds: Optional[Dict[str, int]] = None):
35
+ self.thresholds = dict(DEFAULT_THRESHOLDS)
36
+ if thresholds:
37
+ self.thresholds.update(thresholds)
38
+
39
+ def evaluate_transcript(self, turns: List[Dict[str, Any]]) -> Dict[str, Any]:
40
+ """
41
+ Evaluates a list of turn records:
42
+ turn = {
43
+ "turn_index": int,
44
+ "tool_name": str,
45
+ "command": str,
46
+ "tokens_est": int,
47
+ "has_error": bool,
48
+ "output_length": int
49
+ }
50
+ """
51
+ turn_count = len(turns)
52
+ total_tokens = sum(t.get("tokens_est", 0) for t in turns)
53
+ flags = []
54
+ verdict = "OK"
55
+
56
+ # 1. Turn budget check
57
+ if turn_count >= self.thresholds["max_turns"]:
58
+ flags.append({
59
+ "severity": "CRITICAL",
60
+ "type": "TURN_LIMIT_EXCEEDED",
61
+ "message": f"Turn count ({turn_count}) exceeded maximum threshold ({self.thresholds['max_turns']})."
62
+ })
63
+ verdict = "STOP"
64
+ elif turn_count >= self.thresholds["warn_turns"]:
65
+ flags.append({
66
+ "severity": "WARNING",
67
+ "type": "TURN_LIMIT_WARNING",
68
+ "message": f"Turn count ({turn_count}) approached warning threshold ({self.thresholds['warn_turns']})."
69
+ })
70
+ if verdict == "OK":
71
+ verdict = "WARN"
72
+
73
+ # 2. Token budget check
74
+ if total_tokens >= self.thresholds["max_tokens"]:
75
+ flags.append({
76
+ "severity": "CRITICAL",
77
+ "type": "TOKEN_BUDGET_EXCEEDED",
78
+ "message": f"Estimated token usage ({total_tokens:,}) exceeded budget ({self.thresholds['max_tokens']:,})."
79
+ })
80
+ verdict = "STOP"
81
+ elif total_tokens >= self.thresholds["warn_tokens"]:
82
+ flags.append({
83
+ "severity": "WARNING",
84
+ "type": "TOKEN_BUDGET_WARNING",
85
+ "message": f"Estimated token usage ({total_tokens:,}) reached warning limit ({self.thresholds['warn_tokens']:,})."
86
+ })
87
+ if verdict == "OK":
88
+ verdict = "WARN"
89
+
90
+ # 3. Repeated identical tool call loop detection
91
+ recent_commands = [
92
+ (t.get("command") or t.get("tool_name") or t.get("tool") or t.get("name") or "")
93
+ for t in turns
94
+ if (t.get("command") or t.get("tool_name") or t.get("tool") or t.get("name"))
95
+ ]
96
+ if len(recent_commands) >= self.thresholds["max_repeated_calls"]:
97
+ last_cmd = recent_commands[-1]
98
+ repeat_count = 1
99
+ for cmd in reversed(recent_commands[:-1]):
100
+ if cmd == last_cmd and last_cmd:
101
+ repeat_count += 1
102
+ else:
103
+ break
104
+ if repeat_count >= self.thresholds["max_repeated_calls"]:
105
+ flags.append({
106
+ "severity": "CRITICAL",
107
+ "type": "TOOL_LOOP_DETECTED",
108
+ "message": f"Command repeated {repeat_count} consecutive times: '{last_cmd[:60]}...'"
109
+ })
110
+ verdict = "STOP"
111
+
112
+ # 4. Consecutive empty turns detection
113
+ empty_turns = 0
114
+ for t in reversed(turns):
115
+ if t.get("output_length", 1) == 0 and not t.get("tool_name"):
116
+ empty_turns += 1
117
+ else:
118
+ break
119
+ if empty_turns >= self.thresholds["empty_turn_threshold"]:
120
+ flags.append({
121
+ "severity": "CRITICAL",
122
+ "type": "EMPTY_TURNS_LOOP",
123
+ "message": f"Detected {empty_turns} consecutive empty turns without progress."
124
+ })
125
+ verdict = "STOP"
126
+
127
+ return {
128
+ "verdict": verdict,
129
+ "turn_count": turn_count,
130
+ "total_tokens_est": total_tokens,
131
+ "flags": flags,
132
+ "is_runaway": verdict == "STOP",
133
+ }
134
+
135
+ def main():
136
+ parser = argparse.ArgumentParser(description="Evaluate agent sessions for runaway token consumption and loops.")
137
+ parser.add_argument("--transcript", "-t", help="Path to JSON file containing turn list.")
138
+ parser.add_argument("--turns", type=int, default=0, help="Direct turn count to evaluate.")
139
+ parser.add_argument("--tokens", type=int, default=0, help="Direct token estimate to evaluate.")
140
+ parser.add_argument("--json", action="store_true", help="Output results in JSON format.")
141
+ args = parser.parse_args()
142
+
143
+ sentinel = RunawaySentinel()
144
+
145
+ if args.transcript and os.path.exists(args.transcript):
146
+ with open(args.transcript, "r", encoding="utf-8") as f:
147
+ turns = json.load(f)
148
+ elif args.turns > 0 or args.tokens > 0:
149
+ if args.turns == 0 and args.tokens > 0:
150
+ turns = [{"turn_index": 0, "tokens_est": args.tokens}]
151
+ else:
152
+ turn_count = max(1, args.turns)
153
+ per_turn_tokens = args.tokens // turn_count
154
+ turns = [{"turn_index": i, "tokens_est": per_turn_tokens} for i in range(turn_count)]
155
+ else:
156
+ # Default mock evaluation
157
+ turns = []
158
+
159
+ result = sentinel.evaluate_transcript(turns)
160
+
161
+ if args.json:
162
+ print(json.dumps(result, indent=2, ensure_ascii=False))
163
+ else:
164
+ print(f"[RUNAWAY STOPPER] Verdict: {result['verdict']}")
165
+ print(f" Turns Evaluated: {result['turn_count']}")
166
+ print(f" Estimated Tokens: {result['total_tokens_est']:,}")
167
+ if result["flags"]:
168
+ print(" Flags Detected:")
169
+ for flag in result["flags"]:
170
+ print(f" - [{flag['severity']}] {flag['type']}: {flag['message']}")
171
+ else:
172
+ print(" Status: Clean - zero loops or budget overruns detected.")
173
+
174
+ if result["is_runaway"]:
175
+ sys.exit(1)
176
+
177
+ if __name__ == "__main__":
178
+ main()
@@ -236,7 +236,7 @@ class SynapseUiHandler(BaseHTTPRequestHandler):
236
236
  if path == "/api/status":
237
237
  active_target = JOB_MANAGER.target_dir or REPO_ROOT
238
238
  self.send_json(200, {
239
- "version": "3.8.5",
239
+ "version": "3.9.1",
240
240
  "status": "ONLINE",
241
241
  "os": sys.platform,
242
242
  "workspace": active_target,
@@ -65,7 +65,7 @@ def get_local_version():
65
65
  try:
66
66
  with open(pkg_file, "r", encoding="utf-8") as f:
67
67
  data = json.load(f)
68
- return data.get("version", "3.8.5")
68
+ return data.get("version", "3.9.1")
69
69
  except (OSError, json.JSONDecodeError):
70
70
  data = {}
71
71
 
@@ -74,11 +74,11 @@ def get_local_version():
74
74
  try:
75
75
  with open(manifest_file, "r", encoding="utf-8") as f:
76
76
  data = json.load(f)
77
- return data.get("version", "3.8.5")
77
+ return data.get("version", "3.9.1")
78
78
  except (OSError, json.JSONDecodeError):
79
79
  data = {}
80
80
 
81
- return "3.8.5"
81
+ return "3.9.1"
82
82
 
83
83
 
84
84
  def fetch_remote_version():
@@ -1006,6 +1006,21 @@ def gate_9_skill_collision(repo_root, mode="AUTO"):
1006
1006
  safe_print(res.stderr)
1007
1007
  return False
1008
1008
  print("[PASS] 100% Verified: 0 skill description and rule collisions detected (similarity < 0.75).")
1009
+
1010
+ # Run Mechanical UI Finish Gate (Leonxlnx taste-skill pattern)
1011
+ mech_script = os.path.join(SCRIPT_DIR, "mechanical_ui_gate.py")
1012
+ if not os.path.exists(mech_script):
1013
+ mech_script = os.path.join(repo_root, "tools", "mechanical_ui_gate.py")
1014
+ if os.path.exists(mech_script):
1015
+ try:
1016
+ m_res = subprocess.run([sys.executable, mech_script], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", timeout=30.0)
1017
+ if m_res.returncode == 0:
1018
+ print("[PASS] Mechanical UI Finish Gate: Layout, contrast, and interactive elements verified.")
1019
+ else:
1020
+ safe_print(f"[WARN] Mechanical UI Finish Gate non-zero exit: {m_res.stderr.strip()[:100]}")
1021
+ except (OSError, subprocess.SubprocessError) as m_err:
1022
+ safe_print(f"[WARN] Mechanical UI Finish Gate execution error: {m_err}")
1023
+
1009
1024
  return True
1010
1025
 
1011
1026
 
@@ -47,7 +47,7 @@ def get_hub_metadata() -> Dict[str, Any]:
47
47
  """Retrieves version and catalog count from skills_manifest.json."""
48
48
  manifest_path = os.path.join(HUB_ROOT, "skills_manifest.json")
49
49
  meta = {
50
- "version": "3.8.5",
50
+ "version": "3.9.1",
51
51
  "totalSkills": 42,
52
52
  "author": "Thế Vị (@TeeVee98)",
53
53
  "repo": "https://github.com/TeeVee98/Synapse-Hub"