@teevee98/synapse-hub 3.8.4 → 3.9.0

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 (65) hide show
  1. package/.agents/rules/author-integrity-guard.md +13 -10
  2. package/.agents/rules/skill-precedence.md +6 -4
  3. package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md +1 -1
  4. package/.agents/skills/agentless-qa-repair/SKILL.md +1 -1
  5. package/.agents/skills/auth-session-and-cookie-manager/SKILL.md +22 -2
  6. package/.agents/skills/qa-memory-os/SKILL.md +21 -4
  7. package/.agents/skills/security-dast-sentinel/SKILL.md +1 -1
  8. package/.agents/skills/token-and-context-optimizer/SKILL.md +1 -1
  9. package/.agents/skills/verification-before-completion/SKILL.md +1 -1
  10. package/AGENTS.md +3 -2
  11. package/CLAUDE.md +3 -3
  12. package/NOTICE +48 -0
  13. package/README.en.md +9 -9
  14. package/README.md +9 -9
  15. package/agentskills.json +1 -1
  16. package/bin/agent-qa.js +1 -1
  17. package/docs/ARCHITECTURE.en.md +7 -3
  18. package/docs/ARCHITECTURE.md +6 -2
  19. package/docs/CI_CD_INTEGRATION.en.md +6 -6
  20. package/docs/CI_CD_INTEGRATION.md +6 -6
  21. package/docs/CLI_REFERENCE.md +1 -1
  22. package/docs/PERFORMANCE_AUDIT_REPORT.md +1 -1
  23. package/docs/QUALITY_GATES.en.md +1 -1
  24. package/docs/QUALITY_GATES.md +1 -1
  25. package/docs/adopted-ecosystem-tools.md +37 -0
  26. package/docs/diagrams/clean_pom.svg +48 -0
  27. package/docs/diagrams/fsm_flow.svg +78 -0
  28. package/package.json +1 -1
  29. package/plugin.json +1 -1
  30. package/skills_manifest.json +103 -54
  31. package/synapse.config.json +1 -1
  32. package/templates/PROJECT_AI_GUIDE_TEMPLATE.md +3 -3
  33. package/templates/ai_bridges/CLAUDE.md +3 -3
  34. package/templates/ci/github-actions-synapse.yml +2 -2
  35. package/templates/ci/gitlab-ci-synapse.yml +1 -1
  36. package/templates/ui/index.html +2 -2
  37. package/templates/welcome.html.tmpl +26 -26
  38. package/tools/TOOLS_RUNBOOK.md +8 -8
  39. package/tools/__init__.py +1 -1
  40. package/tools/analyze_project.py +2 -2
  41. package/tools/browser_helpers.js +2 -2
  42. package/tools/build_consolidated_report.py +1640 -0
  43. package/tools/bump_version.py +5 -15
  44. package/tools/cli.py +3 -3
  45. package/tools/count_tokens.py +29 -5
  46. package/tools/dashboard_generator.py +10 -10
  47. package/tools/diagram_architect.py +220 -0
  48. package/tools/distill_log.py +33 -8
  49. package/tools/git_worktree_manager.py +185 -0
  50. package/tools/hub_publisher.py +38 -0
  51. package/tools/humanize_linter.py +4 -0
  52. package/tools/interview_story.py +25 -2
  53. package/tools/mcp_docx_server.py +1 -1
  54. package/tools/mcp_excel_server.py +1 -1
  55. package/tools/mcp_server.py +1 -1
  56. package/tools/mechanical_ui_gate.py +242 -0
  57. package/tools/pairwise_generator.py +175 -0
  58. package/tools/repo_map.py +308 -106
  59. package/tools/runaway_stopper.py +178 -0
  60. package/tools/setup_project.py +3 -3
  61. package/tools/sync_agent_rules.py +3 -3
  62. package/tools/ui_server.py +1 -1
  63. package/tools/update_sentinel.py +6 -6
  64. package/tools/verify_all.py +15 -0
  65. package/tools/welcome_page.py +2 -2
@@ -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()
@@ -248,7 +248,7 @@ elif command -v synapse-hub >/dev/null 2>&1; then
248
248
  elif command -v agent-qa >/dev/null 2>&1; then
249
249
  agent-qa verify
250
250
  elif command -v npx >/dev/null 2>&1; then
251
- npx --no-install synapse-hub verify 2>/dev/null || npx synapse-hub@{pkg_ver} verify
251
+ npx --no-install @teevee98/synapse-hub verify 2>/dev/null || npx @teevee98/synapse-hub@{pkg_ver} verify
252
252
  else
253
253
  echo "\\n[AI-GUARD - REJECTED] No verification engine found (synapse-hub, agent-qa, npx missing)."
254
254
  exit 1
@@ -267,7 +267,7 @@ elif command -v synapse-hub >/dev/null 2>&1; then
267
267
  elif command -v agent-qa >/dev/null 2>&1; then
268
268
  agent-qa analyze
269
269
  elif command -v npx >/dev/null 2>&1; then
270
- npx --no-install synapse-hub analyze 2>/dev/null || npx synapse-hub@{pkg_ver} analyze
270
+ npx --no-install @teevee98/synapse-hub analyze 2>/dev/null || npx @teevee98/synapse-hub@{pkg_ver} analyze
271
271
  fi
272
272
  echo "[AI-GUARD - READY] Pushing to remote...\\n"
273
273
  # --- End Synapse-Hub Quality Gate ---
@@ -388,7 +388,7 @@ def inject_antigravity_global_plugin():
388
388
  """
389
389
  Automatically injects Synapse-Hub into Antigravity's Global Plugin Directory
390
390
  (~/.gemini/config/plugins/synapse-hub).
391
- Ensures that running `npx synapse-hub setup` activates the 53 skills and 9 subagents
391
+ Ensures that running `npx @teevee98/synapse-hub setup` activates the 53 skills and 9 subagents
392
392
  globally across ALL projects in Google Antigravity.
393
393
  """
394
394
  try:
@@ -63,9 +63,9 @@ In accordance with the MIT License, the original copyright notice crediting **Th
63
63
  ---
64
64
 
65
65
  ## ⚡ Quick Commands
66
- - Verify 10 Quality Gates: `npx synapse-hub verify` (or `python tools/verify_all.py`)
67
- - Project Health Audit: `npx synapse-hub analyze` (or `python tools/analyze_project.py`)
68
- - Code Linter & Fake-Pass Sentinel: `npx synapse-hub lint` (or `python tools/infer_linter.py`)
66
+ - Verify 10 Quality Gates: `npx @teevee98/synapse-hub verify` (or `python tools/verify_all.py`)
67
+ - Project Health Audit: `npx @teevee98/synapse-hub analyze` (or `python tools/analyze_project.py`)
68
+ - Code Linter & Fake-Pass Sentinel: `npx @teevee98/synapse-hub lint` (or `python tools/infer_linter.py`)
69
69
  - Verify Author Attribution: `python tools/author_integrity.py`
70
70
  - Skill Security Audit: `python tools/skillspector.py .agents/skills`
71
71
 
@@ -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.4",
239
+ "version": "3.9.0",
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.4")
68
+ return data.get("version", "3.9.0")
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.4")
77
+ return data.get("version", "3.9.0")
78
78
  except (OSError, json.JSONDecodeError):
79
79
  data = {}
80
80
 
81
- return "3.8.4"
81
+ return "3.9.0"
82
82
 
83
83
 
84
84
  def fetch_remote_version():
@@ -87,7 +87,7 @@ def fetch_remote_version():
87
87
 
88
88
  # 1. Primary: NPM Registry
89
89
  try:
90
- req = urllib.request.Request("https://registry.npmjs.org/synapse-hub/latest", headers=headers)
90
+ req = urllib.request.Request("https://registry.npmjs.org/@teevee98/synapse-hub/latest", headers=headers)
91
91
  with urllib.request.urlopen(req, timeout=1.8) as resp: # nosec B310
92
92
  data = json.loads(resp.read().decode("utf-8"))
93
93
  if "version" in data:
@@ -178,7 +178,7 @@ def print_update_banner(local_ver, remote_ver):
178
178
  │ {BOLD}🚀 Synapse-Hub Update Available: {YELLOW}{local_ver}{RESET}{CYAN} → {GREEN}{BOLD}v{remote_ver}{RESET}{CYAN} │
179
179
  │ │
180
180
  │ To upgrade your local hub, run: │
181
- │ 👉 {BOLD}agent-qa update{RESET}{CYAN} or {BOLD}npx synapse-hub update{RESET}{CYAN} │
181
+ │ 👉 {BOLD}agent-qa update{RESET}{CYAN} or {BOLD}npx @teevee98/synapse-hub update{RESET}{CYAN} │
182
182
  │ │
183
183
  │ Repository: {BOLD}https://github.com/TeeVee98/Synapse-Hub{RESET}{CYAN} │
184
184
  └────────────────────────────────────────────────────────────────────────┘{RESET}
@@ -296,7 +296,7 @@ def perform_update():
296
296
  print(f"\n{BOLD}[1/3] Checking NPM package installation...{RESET}")
297
297
  try:
298
298
  res = subprocess.run(
299
- ["npm", "install", "-g", "synapse-hub@latest"],
299
+ ["npm", "install", "-g", "@teevee98/synapse-hub@latest"],
300
300
  stdout=subprocess.PIPE,
301
301
  stderr=subprocess.PIPE,
302
302
  text=True,
@@ -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.4",
50
+ "version": "3.9.0",
51
51
  "totalSkills": 42,
52
52
  "author": "Thế Vị (@TeeVee98)",
53
53
  "repo": "https://github.com/TeeVee98/Synapse-Hub"
@@ -283,7 +283,7 @@ def main():
283
283
  mark_first_run_completed(target_dir)
284
284
 
285
285
  print(f"✅ Landing page generated successfully at:\n file://{out_path}")
286
- print("👉 You can re-open it anytime with: npx synapse-hub welcome")
286
+ print("👉 You can re-open it anytime with: npx @teevee98/synapse-hub welcome")
287
287
 
288
288
 
289
289
  if __name__ == "__main__":