@teevee98/synapse-hub 0.0.0-stage → 3.8.2

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 (369) hide show
  1. package/.agents/agents/api-engineer.md +67 -0
  2. package/.agents/agents/failure-analyst.md +75 -0
  3. package/.agents/agents/live-explorer.md +70 -0
  4. package/.agents/agents/orchestrator.md +104 -0
  5. package/.agents/agents/perf-engineer.md +74 -0
  6. package/.agents/agents/pom-crafter.md +112 -0
  7. package/.agents/agents/quality-gatekeeper.md +87 -0
  8. package/.agents/agents/test-designer.md +73 -0
  9. package/.agents/agents/test-runner.md +67 -0
  10. package/.agents/rules/author-integrity-guard.md +33 -0
  11. package/.agents/rules/communication-style.md +18 -0
  12. package/.agents/rules/context-engineering.md +37 -0
  13. package/.agents/rules/git-push-protocol.md +33 -0
  14. package/.agents/rules/graphify.md +14 -0
  15. package/.agents/rules/lessons-learned.md +25 -0
  16. package/.agents/rules/mandatory-playwright-live.md +25 -0
  17. package/.agents/rules/mobile_appium_rules.md +43 -0
  18. package/.agents/rules/performance_testing_rules.md +35 -0
  19. package/.agents/rules/skill-precedence.md +29 -0
  20. package/.agents/rules/systematic-debugging.md +36 -0
  21. package/.agents/skills/actor-qa-swarm/SKILL.md +77 -0
  22. package/.agents/skills/actor-qa-swarm/examples/broker_sharding_sample.json +12 -0
  23. package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md +88 -0
  24. package/.agents/skills/agent-orchestration-multi-agent-optimize/examples/swarm_workload_config.json +15 -0
  25. package/.agents/skills/agentless-qa-repair/SKILL.md +69 -0
  26. package/.agents/skills/agentless-qa-repair/examples/healing_report_sample.json +17 -0
  27. package/.agents/skills/agentless-qa-repair/examples/three_phase_repair_workflow.md +40 -0
  28. package/.agents/skills/antigravity-test-sentinel/SKILL.md +63 -0
  29. package/.agents/skills/antigravity-test-sentinel/examples/dod_gate_policy.json +11 -0
  30. package/.agents/skills/antigravity-test-sentinel/examples/sprint_dod_enforcement.md +47 -0
  31. package/.agents/skills/api-network-mocking-interception/SKILL.md +142 -0
  32. package/.agents/skills/api-network-mocking-interception/examples/network_route_stub.json +9 -0
  33. package/.agents/skills/api-spec-to-e2e-matrix/SKILL.md +80 -0
  34. package/.agents/skills/api-spec-to-e2e-matrix/examples/sample_openapi.json +19 -0
  35. package/.agents/skills/architecture-decision-records/SKILL.md +64 -0
  36. package/.agents/skills/architecture-decision-records/examples/0001-record-architecture-decisions.md +12 -0
  37. package/.agents/skills/auth-session-and-cookie-manager/SKILL.md +75 -0
  38. package/.agents/skills/auth-session-and-cookie-manager/examples/multi_role_auth_matrix.md +70 -0
  39. package/.agents/skills/auth-session-and-cookie-manager/examples/storage_state_sample.json +11 -0
  40. package/.agents/skills/backend-load-and-stress-patterns/SKILL.md +85 -0
  41. package/.agents/skills/backend-load-and-stress-patterns/examples/k6_load_test_sample.js +13 -0
  42. package/.agents/skills/backend-load-and-stress-patterns/references/k6_load_template.js +82 -0
  43. package/.agents/skills/bats-testing-patterns/SKILL.md +100 -0
  44. package/.agents/skills/bats-testing-patterns/examples/cli_runner_test.bats +6 -0
  45. package/.agents/skills/bats-testing-patterns/resources/implementation-playbook.md +614 -0
  46. package/.agents/skills/clean-pom-crafter/SKILL.md +110 -0
  47. package/.agents/skills/clean-pom-crafter/examples/standard_test_case.groovy +28 -0
  48. package/.agents/skills/clean-pom-crafter/references/pom_patterns.groovy +138 -0
  49. package/.agents/skills/code-refactoring-refactor-clean/SKILL.md +64 -0
  50. package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +9 -0
  51. package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +52 -0
  52. package/.agents/skills/code-refactoring-refactor-clean/resources/implementation-playbook.md +881 -0
  53. package/.agents/skills/consumer-driven-contract-testing/SKILL.md +147 -0
  54. package/.agents/skills/consumer-driven-contract-testing/examples/order_service_pact.json +45 -0
  55. package/.agents/skills/db-state-verifier-and-seeder/SKILL.md +123 -0
  56. package/.agents/skills/db-state-verifier-and-seeder/examples/db_fixture_seed.json +12 -0
  57. package/.agents/skills/e2e-testing-patterns/SKILL.md +103 -0
  58. package/.agents/skills/e2e-testing-patterns/examples/playwright_sharded_config.ts +12 -0
  59. package/.agents/skills/e2e-testing-patterns/resources/implementation-playbook.md +522 -0
  60. package/.agents/skills/event-stream-qa-orchestrator/SKILL.md +79 -0
  61. package/.agents/skills/event-stream-qa-orchestrator/examples/timeline_sample.jsonl +2 -0
  62. package/.agents/skills/failure-autopsy-and-healing/SKILL.md +66 -0
  63. package/.agents/skills/failure-autopsy-and-healing/examples/closed_loop_healing_walkthrough.md +48 -0
  64. package/.agents/skills/failure-autopsy-and-healing/examples/sample_junit_failure.xml +8 -0
  65. package/.agents/skills/failure-autopsy-and-healing/references/healing_matrix.md +64 -0
  66. package/.agents/skills/failure-autopsy-and-healing/references/qa_investigation_protocol.md +56 -0
  67. package/.agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh +83 -0
  68. package/.agents/skills/file-and-report-validator/SKILL.md +90 -0
  69. package/.agents/skills/file-and-report-validator/examples/sample_export_schema.json +14 -0
  70. package/.agents/skills/flaky-test-sentinel-and-quarantine/SKILL.md +114 -0
  71. package/.agents/skills/flaky-test-sentinel-and-quarantine/examples/quarantine_registry.json +11 -0
  72. package/.agents/skills/gherkin-to-suite/SKILL.md +103 -0
  73. package/.agents/skills/gherkin-to-suite/examples/checkout.feature +39 -0
  74. package/.agents/skills/gherkin-to-suite/examples/suite_report_sample.json +334 -0
  75. package/.agents/skills/github-actions-templates/SKILL.md +77 -0
  76. package/.agents/skills/github-actions-templates/examples/matrix_test_pipeline.yml +8 -0
  77. package/.agents/skills/graphify-impact-analyzer/SKILL.md +76 -0
  78. package/.agents/skills/graphify-impact-analyzer/examples/dependency_blast_radius.json +8 -0
  79. package/.agents/skills/katalon-cli-runner/SKILL.md +76 -0
  80. package/.agents/skills/katalon-cli-runner/examples/headless_kre_exec.sh +3 -0
  81. package/.agents/skills/katalon-cli-runner/references/groovy-patterns.md +209 -0
  82. package/.agents/skills/katalon-cli-runner/references/katalon-api.md +155 -0
  83. package/.agents/skills/katalon-cli-runner/references/runner_commands.md +67 -0
  84. package/.agents/skills/lam-script-generator/SKILL.md +123 -0
  85. package/.agents/skills/lam-script-generator/examples/user_story_sample.md +8 -0
  86. package/.agents/skills/lean-code-ladder/SKILL.md +94 -0
  87. package/.agents/skills/lean-code-ladder/examples/ladder_walkthrough.md +37 -0
  88. package/.agents/skills/lean-impact-scoreboard/SKILL.md +48 -0
  89. package/.agents/skills/lean-impact-scoreboard/examples/sample_benchmark_gain.md +20 -0
  90. package/.agents/skills/lean-impact-scoreboard/examples/sample_scoreboard.md +15 -0
  91. package/.agents/skills/meta-prompt-crafter/SKILL.md +107 -0
  92. package/.agents/skills/meta-prompt-crafter/examples/qa_prompt_template.md +35 -0
  93. package/.agents/skills/mipro-prompt-compiler/SKILL.md +59 -0
  94. package/.agents/skills/mipro-prompt-compiler/examples/compiled_module_sample.json +22 -0
  95. package/.agents/skills/mipro-prompt-compiler/examples/dspy_assertion_optimizer_case.md +46 -0
  96. package/.agents/skills/mobile-appium-som/SKILL.md +88 -0
  97. package/.agents/skills/mobile-appium-som/examples/BaseScreen.java +88 -0
  98. package/.agents/skills/mobile-appium-som/examples/LoginScreen.java +46 -0
  99. package/.agents/skills/mobile-appium-som/examples/TC_MobileLogin.java +43 -0
  100. package/.agents/skills/persistent-planning-files/SKILL.md +108 -0
  101. package/.agents/skills/persistent-planning-files/examples/task_plan_example.md +56 -0
  102. package/.agents/skills/playwright-live-interaction/SKILL.md +131 -0
  103. package/.agents/skills/playwright-live-interaction/examples/live_probe_script.js +5 -0
  104. package/.agents/skills/playwright-live-interaction/references/advanced_superpowers.md +160 -0
  105. package/.agents/skills/playwright-live-interaction/references/compact_accessibility_snapshots.md +75 -0
  106. package/.agents/skills/playwright-live-interaction/references/recipes.md +388 -0
  107. package/.agents/skills/playwright-live-interaction/references/swarm_orchestration.md +134 -0
  108. package/.agents/skills/playwright-webapp-testing/SKILL.md +93 -0
  109. package/.agents/skills/playwright-webapp-testing/examples/server_lifecycle_playwright.py +63 -0
  110. package/.agents/skills/qa-aci-interface/SKILL.md +67 -0
  111. package/.agents/skills/qa-aci-interface/examples/surgical_code_window_walkthrough.md +40 -0
  112. package/.agents/skills/qa-aci-interface/examples/surgical_edit_sample.json +12 -0
  113. package/.agents/skills/qa-memory-os/SKILL.md +80 -0
  114. package/.agents/skills/qa-memory-os/examples/archival_memory_sample.json +21 -0
  115. package/.agents/skills/rbt-manual-testing/SKILL.md +137 -0
  116. package/.agents/skills/rbt-manual-testing/examples/checkout_rbt_manual_suite.md +25 -0
  117. package/.agents/skills/rbt-manual-testing/references/field_validation_checklist.md +29 -0
  118. package/.agents/skills/repo-quality-audit/SKILL.md +68 -0
  119. package/.agents/skills/repo-quality-audit/examples/sample_audit_walkthrough.md +15 -0
  120. package/.agents/skills/repo-quality-audit/examples/sample_repo_audit.md +33 -0
  121. package/.agents/skills/review-spec/SKILL.md +60 -0
  122. package/.agents/skills/review-spec/examples/pocock_grilling_decision_rubric.md +40 -0
  123. package/.agents/skills/review-spec/examples/sample_spec_review.md +33 -0
  124. package/.agents/skills/security-dast-sentinel/SKILL.md +119 -0
  125. package/.agents/skills/security-dast-sentinel/examples/dast_scan_config.json +10 -0
  126. package/.agents/skills/security-dast-sentinel/references/AI-AND-LLM.md +113 -0
  127. package/.agents/skills/security-dast-sentinel/references/ATTACK-CLASSES.md +89 -0
  128. package/.agents/skills/security-dast-sentinel/references/dast_recipes.ts +33 -0
  129. package/.agents/skills/self-healing-locator/SKILL.md +86 -0
  130. package/.agents/skills/self-healing-locator/examples/aom_diff_sample.json +16 -0
  131. package/.agents/skills/senior-code-review/SKILL.md +108 -0
  132. package/.agents/skills/senior-code-review/examples/sample_review_walkthrough.md +29 -0
  133. package/.agents/skills/skillspector-security-guard/SKILL.md +57 -0
  134. package/.agents/skills/skillspector-security-guard/examples/audit_threat_vectors_report.json +35 -0
  135. package/.agents/skills/skillspector-security-guard/examples/safe_mcp_config.json +12 -0
  136. package/.agents/skills/surgical-coding-principles/SKILL.md +89 -0
  137. package/.agents/skills/surgical-coding-principles/examples/surgical_vs_scope_creep.md +46 -0
  138. package/.agents/skills/synthetic-test-data-generator/SKILL.md +135 -0
  139. package/.agents/skills/synthetic-test-data-generator/examples/idempotent_data_recipe.json +9 -0
  140. package/.agents/skills/systematic-debugging/SKILL.md +100 -0
  141. package/.agents/skills/systematic-debugging/examples/four_phase_case.md +44 -0
  142. package/.agents/skills/technical-debt-harvester/SKILL.md +70 -0
  143. package/.agents/skills/technical-debt-harvester/examples/sample_debt_ledger.md +25 -0
  144. package/.agents/skills/technical-debt-harvester/examples/sample_ledger_output.md +20 -0
  145. package/.agents/skills/test-driven-development/SKILL.md +114 -0
  146. package/.agents/skills/test-driven-development/examples/red_green_refactor_qa.md +78 -0
  147. package/.agents/skills/token-and-context-optimizer/SKILL.md +70 -0
  148. package/.agents/skills/token-and-context-optimizer/examples/distilled_log_sample.txt +3 -0
  149. package/.agents/skills/token-and-context-optimizer/references/context_engineering_guide.md +49 -0
  150. package/.agents/skills/tot-exploratory-testing/SKILL.md +59 -0
  151. package/.agents/skills/tot-exploratory-testing/examples/payment_gateway_tot_tree.json +62 -0
  152. package/.agents/skills/tot-exploratory-testing/examples/tot_graph_sample.json +35 -0
  153. package/.agents/skills/verification-before-completion/SKILL.md +100 -0
  154. package/.agents/skills/verification-before-completion/examples/evidence_log_example.md +46 -0
  155. package/.agents/skills/visual-regression-sentinel/SKILL.md +82 -0
  156. package/.agents/skills/visual-regression-sentinel/examples/visual_mask_rules.json +9 -0
  157. package/.agents/skills/wcag-audit-patterns/SKILL.md +77 -0
  158. package/.agents/skills/wcag-audit-patterns/examples/wcag_compliance_checklist.json +10 -0
  159. package/.agents/skills/wcag-audit-patterns/resources/implementation-playbook.md +541 -0
  160. package/.agents/skills/web-agent-gym-benchmarking/SKILL.md +62 -0
  161. package/.agents/skills/web-agent-gym-benchmarking/examples/benchmark_report_sample.json +22 -0
  162. package/.agents/skills/web-agent-gym-benchmarking/examples/enterprise_tasks_suite.json +38 -0
  163. package/.agents/skills/web-vitals-and-performance-profiler/SKILL.md +65 -0
  164. package/.agents/skills/web-vitals-and-performance-profiler/examples/cwv_budget_policy.json +6 -0
  165. package/.agents/skills/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +118 -0
  166. package/.agents/templates/completion_report.md +57 -0
  167. package/.agents/workflows/analyze_requirement_document.md +18 -0
  168. package/.agents/workflows/export_testcases_excel.md +32 -0
  169. package/.agents/workflows/generate_combinatorial_test_data.md +28 -0
  170. package/.agents/workflows/generate_cross_module_test_plan.md +37 -0
  171. package/.agents/workflows/generate_manual_testcases_rbt.md +56 -0
  172. package/.agents/workflows/generate_requirements_from_website.md +25 -0
  173. package/.agents/workflows/generate_testcases_from_requirements.md +21 -0
  174. package/.agents/workflows/graphify.md +10 -0
  175. package/.agents/workflows/test-impact.md +15 -0
  176. package/.agents/workflows/verify.md +34 -0
  177. package/.cursor/rules/agents.mdc +16 -0
  178. package/.cursor/rules/language.mdc +7 -0
  179. package/.cursor/rules/synapse-qa.mdc +24 -0
  180. package/.cursorrules +27 -0
  181. package/.dockerignore +53 -0
  182. package/.pre-commit-hooks.yaml +14 -0
  183. package/.windsurfrules +26 -0
  184. package/AGENTS.md +86 -0
  185. package/CLAUDE.md +54 -0
  186. package/Dockerfile +81 -0
  187. package/LICENSE +52 -0
  188. package/NOTICE +264 -0
  189. package/README.en.md +172 -0
  190. package/README.md +171 -2
  191. package/action.yml +51 -0
  192. package/agentskills.json +16 -0
  193. package/bin/agent-qa.js +138 -0
  194. package/docker-compose.yml +74 -0
  195. package/docs/ARCHITECTURE.en.md +197 -0
  196. package/docs/ARCHITECTURE.md +198 -0
  197. package/docs/CI_CD_INTEGRATION.en.md +170 -0
  198. package/docs/CI_CD_INTEGRATION.md +170 -0
  199. package/docs/CLI_REFERENCE.en.md +175 -0
  200. package/docs/CLI_REFERENCE.md +177 -0
  201. package/docs/CONTRIBUTING.en.md +49 -0
  202. package/docs/CONTRIBUTING.md +49 -0
  203. package/docs/PERFORMANCE_AUDIT_REPORT.md +784 -0
  204. package/docs/PLUGIN_DEVELOPMENT_GUIDE.md +127 -0
  205. package/docs/QUALITY_GATES.en.md +121 -0
  206. package/docs/QUALITY_GATES.md +121 -0
  207. package/docs/TOKEN_QUOTA_PLAYBOOK.md +41 -0
  208. package/docs/TOOL_CATALOG.md +129 -0
  209. package/docs/adopted-ecosystem-tools.md +96 -0
  210. package/docs/research/EXTERNAL_AGENT_SKILLS_SURVEY.md +1062 -0
  211. package/docs/research/agent_skill_training_analysis.md +1359 -0
  212. package/docs/schemas/synapse.config.schema.json +87 -0
  213. package/package.json +94 -4
  214. package/plugin.json +31 -0
  215. package/scripts/generate_skill_examples.py +244 -0
  216. package/scripts/install.ps1 +112 -0
  217. package/scripts/install_global_plugin.ps1 +94 -0
  218. package/scripts/install_global_plugin.sh +49 -0
  219. package/scripts/lint_skills.ps1 +57 -0
  220. package/scripts/package_dist.py +337 -0
  221. package/scripts/setup.sh +59 -0
  222. package/scripts/update_hub.ps1 +19 -0
  223. package/scripts/update_hub.sh +15 -0
  224. package/skills_manifest.json +854 -0
  225. package/synapse.config.json +32 -0
  226. package/templates/PROJECT_AI_GUIDE_TEMPLATE.md +111 -0
  227. package/templates/PROJECT_STATE_TEMPLATE.md +20 -0
  228. package/templates/ai_bridges/CLAUDE.md +54 -0
  229. package/templates/ai_bridges/copilot-instructions.md +20 -0
  230. package/templates/ai_bridges/cursor_synapse_qa.mdc +24 -0
  231. package/templates/ai_bridges/windsurfrules +26 -0
  232. package/templates/ci/github-actions-synapse.yml +95 -0
  233. package/templates/ci/gitlab-ci-synapse.yml +16 -0
  234. package/templates/ui/index.html +1069 -0
  235. package/templates/welcome.html.tmpl +2079 -0
  236. package/tools/.infer_baseline.json +30 -0
  237. package/tools/TOOLS_RUNBOOK.md +1553 -0
  238. package/tools/TOOL_CATALOG.json +1769 -0
  239. package/tools/__init__.py +43 -0
  240. package/tools/_openapi_parser.py +158 -0
  241. package/tools/agent_canary.py +525 -0
  242. package/tools/agentless_patcher.py +417 -0
  243. package/tools/analyze_project.py +258 -0
  244. package/tools/api_drift_sentinel.py +208 -0
  245. package/tools/api_fuzzer.py +762 -0
  246. package/tools/author_integrity.py +184 -0
  247. package/tools/auto_heal.py +271 -0
  248. package/tools/auto_heal_reflexion.py +532 -0
  249. package/tools/autogen_qa_broker.py +844 -0
  250. package/tools/benchmark_swarm_context.py +394 -0
  251. package/tools/browser_helpers.js +746 -0
  252. package/tools/browsergym_eval.py +236 -0
  253. package/tools/bug_reporter.py +252 -0
  254. package/tools/bump_version.py +423 -0
  255. package/tools/cache_resolver.py +1214 -0
  256. package/tools/check_env.py +426 -0
  257. package/tools/check_version_sync.py +256 -0
  258. package/tools/ci_healing_hook.py +126 -0
  259. package/tools/cli.py +1598 -0
  260. package/tools/config_decoupler.py +253 -0
  261. package/tools/contract_validator.py +141 -0
  262. package/tools/core/__init__.py +70 -0
  263. package/tools/core/adapters.py +431 -0
  264. package/tools/core/circuit_breaker.py +263 -0
  265. package/tools/core/cli_runtime.py +66 -0
  266. package/tools/core/file_lock.py +159 -0
  267. package/tools/core/i18n.py +394 -0
  268. package/tools/core/memory_bus.py +905 -0
  269. package/tools/core/process_supervisor.py +332 -0
  270. package/tools/core/telemetry.py +329 -0
  271. package/tools/count_tokens.py +1267 -0
  272. package/tools/create_mock_docx.py +104 -0
  273. package/tools/dashboard_generator.py +2419 -0
  274. package/tools/db_sandbox.py +675 -0
  275. package/tools/debt_harvester.py +237 -0
  276. package/tools/distill_log.py +161 -0
  277. package/tools/dspy_qa_signatures.py +356 -0
  278. package/tools/e2e_flow_prober.py +132 -0
  279. package/tools/export_postman_collection.py +945 -0
  280. package/tools/flaky_detector.py +389 -0
  281. package/tools/fsm_enforcer.py +450 -0
  282. package/tools/fsm_middleware.py +401 -0
  283. package/tools/fuzz_payloads.py +197 -0
  284. package/tools/generate_allure_report.py +88 -0
  285. package/tools/generate_api_matrix.py +193 -0
  286. package/tools/generate_jmx_plan.py +1322 -0
  287. package/tools/generate_sbom.py +252 -0
  288. package/tools/generate_tc_from_story.py +203 -0
  289. package/tools/generate_test_reports.py +133 -0
  290. package/tools/generate_tool_catalog.py +482 -0
  291. package/tools/gherkin_suite.py +758 -0
  292. package/tools/git_pre_commit_guard.py +298 -0
  293. package/tools/goldfish_review.py +366 -0
  294. package/tools/heal/__init__.py +28 -0
  295. package/tools/heal_pr_automator.py +220 -0
  296. package/tools/heuristic_locator_matcher.py +351 -0
  297. package/tools/hub_publisher.py +623 -0
  298. package/tools/humanize_linter.py +438 -0
  299. package/tools/infer_linter.py +977 -0
  300. package/tools/init_config.py +307 -0
  301. package/tools/interview_story.py +116 -0
  302. package/tools/jira_sync.py +566 -0
  303. package/tools/jtl_analyzer.py +474 -0
  304. package/tools/lint/__init__.py +30 -0
  305. package/tools/lint_ai_docs.py +374 -0
  306. package/tools/lookup_tc.py +165 -0
  307. package/tools/lookup_xpath.py +167 -0
  308. package/tools/matrix_sharder.py +148 -0
  309. package/tools/mcp/__init__.py +18 -0
  310. package/tools/mcp_docx_server.ps1 +13 -0
  311. package/tools/mcp_docx_server.py +851 -0
  312. package/tools/mcp_excel_server.ps1 +13 -0
  313. package/tools/mcp_excel_server.py +441 -0
  314. package/tools/mcp_server.py +724 -0
  315. package/tools/md_to_xlsx.py +327 -0
  316. package/tools/micro_mutator.py +887 -0
  317. package/tools/mipro_assertion_tuner.py +210 -0
  318. package/tools/network_mock_shield.py +311 -0
  319. package/tools/newman_analyzer.py +384 -0
  320. package/tools/omni_emitter.py +579 -0
  321. package/tools/omni_parser.py +450 -0
  322. package/tools/omni_transpiler.py +168 -0
  323. package/tools/openxml_guard.py +438 -0
  324. package/tools/output_formatter.py +182 -0
  325. package/tools/package_release.py +325 -0
  326. package/tools/perf/__init__.py +24 -0
  327. package/tools/pinpoint_failure.py +190 -0
  328. package/tools/project_state.py +171 -0
  329. package/tools/qa_event_stream.py +358 -0
  330. package/tools/repo_map.py +346 -0
  331. package/tools/report/__init__.py +32 -0
  332. package/tools/reversible_sandbox.py +344 -0
  333. package/tools/safety_firewall.py +437 -0
  334. package/tools/security_coverage_ledger.py +538 -0
  335. package/tools/security_scanner.py +229 -0
  336. package/tools/senior_code_review.py +393 -0
  337. package/tools/setup_project.py +770 -0
  338. package/tools/skill_collision_guard.py +304 -0
  339. package/tools/skill_profiles.py +217 -0
  340. package/tools/skill_vault.py +481 -0
  341. package/tools/skillspector.py +1278 -0
  342. package/tools/smart_visual_masker.py +132 -0
  343. package/tools/spec_drift_sentinel.py +438 -0
  344. package/tools/swe_qa_aci.py +369 -0
  345. package/tools/synapse_observer.py +485 -0
  346. package/tools/synapse_qa_bench.py +190 -0
  347. package/tools/sync_agent_rules.py +274 -0
  348. package/tools/telemetry_correlator.py +397 -0
  349. package/tools/template_excel_exporter.py +514 -0
  350. package/tools/templates/jmeter-distributed/README.md +54 -0
  351. package/tools/templates/jmeter-distributed/docker-compose.yml +83 -0
  352. package/tools/test_impact.py +419 -0
  353. package/tools/test_memory_os.py +462 -0
  354. package/tools/textgrad_mutation_optimizer.py +237 -0
  355. package/tools/tms_sync_bridge.py +834 -0
  356. package/tools/tot_exploratory_tester.py +239 -0
  357. package/tools/trace_data_flow.py +240 -0
  358. package/tools/traffic_session_converter.py +256 -0
  359. package/tools/trend_analytics.py +314 -0
  360. package/tools/ui_server.py +401 -0
  361. package/tools/universal_ir.py +488 -0
  362. package/tools/update_sentinel.py +383 -0
  363. package/tools/validate_groovy_scripts.py +173 -0
  364. package/tools/verify_all.py +1259 -0
  365. package/tools/visual_diff_canvas.py +143 -0
  366. package/tools/visual_som_helper.py +550 -0
  367. package/tools/watch_mode.py +308 -0
  368. package/tools/wcag_audit.py +239 -0
  369. package/tools/welcome_page.py +290 -0
@@ -0,0 +1,844 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
5
+
6
+ """
7
+ Asynchronous Actor QA Message Broker (Microsoft AutoGen v0.4+ Pattern)
8
+ -----------------------------------------------------------------------
9
+ Provides an asynchronous Actor-model message broker and matrix sharding coordinator:
10
+ 1. Mailbox-Based Actor Messaging: Decoupled peer-to-peer message passing across QA subagents.
11
+ 2. Pub/Sub Event Dispatch: Asynchronous event publishing (TEST_FAILED, SHARD_COMPLETED, MUTATION_ALERT).
12
+ 3. Parallel Matrix Sharding: Partitions large test suites across worker actors with zero blocking.
13
+ 4. Deadlock & Starvation Sentinel: Enforces 300s timeout ceilings and detects circular dependency deadlocks.
14
+ 5. Multi-Process Concurrency & ACID Durability: SQLite WAL backend eliminates lost updates and race conditions.
15
+
16
+ Usage:
17
+ python tools/autogen_qa_broker.py send-message --from-actor test-runner --to-actor failure-analyst --topic TEST_FAILED --payload '{"test": "login.spec.ts"}'
18
+ python tools/autogen_qa_broker.py fetch-messages --actor failure-analyst
19
+ python tools/autogen_qa_broker.py dispatch-shards --suite-manifest tests/manifest.json --shard-count 4
20
+ python tools/autogen_qa_broker.py check-health
21
+ """
22
+
23
+ import os
24
+ import sys
25
+ import json
26
+ import time
27
+ import uuid
28
+ import sqlite3
29
+ import argparse
30
+ from abc import ABC, abstractmethod
31
+ from datetime import datetime, timezone
32
+ from typing import Dict, Any, List, Optional
33
+
34
+ # Enforce UTF-8 stdout encoding
35
+ if hasattr(sys.stdout, 'reconfigure'):
36
+ try:
37
+ sys.stdout.reconfigure(encoding='utf-8')
38
+ sys.stderr.reconfigure(encoding='utf-8')
39
+ except Exception as err:
40
+ _ = err
41
+
42
+
43
+ class StorageBackend(ABC):
44
+ """Abstract storage backend for Actor QA Message Broker."""
45
+
46
+ @abstractmethod
47
+ def init_backend(self) -> None:
48
+ """Initialize schema, tables, or collections."""
49
+ pass
50
+
51
+ @abstractmethod
52
+ def save_message(
53
+ self,
54
+ msg_id: str,
55
+ from_actor: str,
56
+ to_actor: str,
57
+ topic: str,
58
+ payload_str: str,
59
+ now_iso: str,
60
+ now_epoch: float,
61
+ ) -> None:
62
+ """Persist a message."""
63
+ pass
64
+
65
+ @abstractmethod
66
+ def fetch_messages(
67
+ self,
68
+ actor: str,
69
+ topic: Optional[str] = None,
70
+ mark_read: bool = True,
71
+ ) -> List[Dict[str, Any]]:
72
+ """Fetch messages for an actor."""
73
+ pass
74
+
75
+ @abstractmethod
76
+ def save_subscription(
77
+ self,
78
+ actor: str,
79
+ event_topic: str,
80
+ handler: str,
81
+ subscribed_at: str,
82
+ ) -> int:
83
+ """Subscribe actor to topic and return total subscribers for topic."""
84
+ pass
85
+
86
+ @abstractmethod
87
+ def get_subscribers(self, event_topic: str) -> List[str]:
88
+ """Get list of subscribed actor names for an event topic."""
89
+ pass
90
+
91
+ @abstractmethod
92
+ def get_state(self) -> Dict[str, Any]:
93
+ """Return full state representation (mailboxes, subscriptions, metadata)."""
94
+ pass
95
+
96
+ @abstractmethod
97
+ def check_health(self, timeout_sec: float = 300.0) -> Dict[str, Any]:
98
+ """Perform health check and deadlock detection."""
99
+ pass
100
+
101
+
102
+ class SQLiteStorageBackend(StorageBackend):
103
+ """SQLite WAL storage backend for Actor QA Message Broker."""
104
+
105
+ def __init__(self, state_file: str):
106
+ self.state_file = state_file
107
+ os.makedirs(os.path.dirname(os.path.abspath(self.state_file)), exist_ok=True)
108
+ self.init_backend()
109
+
110
+ def get_connection(self) -> sqlite3.Connection:
111
+ conn = sqlite3.connect(self.state_file, timeout=60.0)
112
+ conn.execute("PRAGMA journal_mode=WAL;")
113
+ conn.execute("PRAGMA busy_timeout=60000;")
114
+ conn.row_factory = sqlite3.Row
115
+ return conn
116
+
117
+ def init_backend(self) -> None:
118
+ with self.get_connection() as conn:
119
+ conn.executescript("""
120
+ CREATE TABLE IF NOT EXISTS messages (
121
+ id TEXT PRIMARY KEY,
122
+ from_actor TEXT NOT NULL,
123
+ to_actor TEXT NOT NULL,
124
+ topic TEXT NOT NULL,
125
+ payload TEXT NOT NULL,
126
+ timestamp TEXT NOT NULL,
127
+ created_at REAL NOT NULL,
128
+ read INTEGER NOT NULL DEFAULT 0
129
+ );
130
+ CREATE INDEX IF NOT EXISTS idx_messages_to_actor ON messages(to_actor, read);
131
+ CREATE INDEX IF NOT EXISTS idx_messages_topic ON messages(topic);
132
+
133
+ CREATE TABLE IF NOT EXISTS subscriptions (
134
+ actor TEXT NOT NULL,
135
+ event_topic TEXT NOT NULL,
136
+ handler TEXT NOT NULL,
137
+ subscribed_at TEXT NOT NULL,
138
+ PRIMARY KEY(actor, event_topic)
139
+ );
140
+
141
+ CREATE TABLE IF NOT EXISTS metadata (
142
+ key TEXT PRIMARY KEY,
143
+ value TEXT NOT NULL
144
+ );
145
+ """)
146
+
147
+ def save_message(
148
+ self,
149
+ msg_id: str,
150
+ from_actor: str,
151
+ to_actor: str,
152
+ topic: str,
153
+ payload_str: str,
154
+ now_iso: str,
155
+ now_epoch: float,
156
+ ) -> None:
157
+ with self.get_connection() as conn:
158
+ conn.execute(
159
+ """
160
+ INSERT INTO messages (id, from_actor, to_actor, topic, payload, timestamp, created_at, read)
161
+ VALUES (?, ?, ?, ?, ?, ?, ?, 0)
162
+ """,
163
+ (msg_id, from_actor, to_actor, topic, payload_str, now_iso, now_epoch)
164
+ )
165
+
166
+ def fetch_messages(
167
+ self,
168
+ actor: str,
169
+ topic: Optional[str] = None,
170
+ mark_read: bool = True,
171
+ ) -> List[Dict[str, Any]]:
172
+ with self.get_connection() as conn:
173
+ cur = conn.cursor()
174
+ if topic:
175
+ cur.execute(
176
+ "SELECT * FROM messages WHERE to_actor = ? AND topic = ? ORDER BY created_at ASC",
177
+ (actor, topic)
178
+ )
179
+ else:
180
+ cur.execute(
181
+ "SELECT * FROM messages WHERE to_actor = ? ORDER BY created_at ASC",
182
+ (actor,)
183
+ )
184
+
185
+ rows = cur.fetchall()
186
+ messages: List[Dict[str, Any]] = []
187
+ msg_ids_to_mark: List[str] = []
188
+
189
+ for row in rows:
190
+ try:
191
+ payload = json.loads(row["payload"])
192
+ except Exception as err:
193
+ _ = err
194
+ payload = row["payload"]
195
+
196
+ messages.append({
197
+ "id": row["id"],
198
+ "from_actor": row["from_actor"],
199
+ "to_actor": row["to_actor"],
200
+ "topic": row["topic"],
201
+ "payload": payload,
202
+ "timestamp": row["timestamp"],
203
+ "read": True if mark_read else bool(row["read"])
204
+ })
205
+ if mark_read and not row["read"]:
206
+ msg_ids_to_mark.append(row["id"])
207
+
208
+ if mark_read and msg_ids_to_mark:
209
+ conn.executemany(
210
+ "UPDATE messages SET read = 1 WHERE id = ?",
211
+ [(mid,) for mid in msg_ids_to_mark]
212
+ )
213
+
214
+ return messages
215
+
216
+ def save_subscription(
217
+ self,
218
+ actor: str,
219
+ event_topic: str,
220
+ handler: str,
221
+ subscribed_at: str,
222
+ ) -> int:
223
+ with self.get_connection() as conn:
224
+ conn.execute(
225
+ """
226
+ INSERT OR REPLACE INTO subscriptions (actor, event_topic, handler, subscribed_at)
227
+ VALUES (?, ?, ?, ?)
228
+ """,
229
+ (actor, event_topic, handler, subscribed_at)
230
+ )
231
+ cur = conn.cursor()
232
+ cur.execute("SELECT COUNT(*) FROM subscriptions WHERE event_topic = ?", (event_topic,))
233
+ return cur.fetchone()[0]
234
+
235
+ def get_subscribers(self, event_topic: str) -> List[str]:
236
+ with self.get_connection() as conn:
237
+ cur = conn.cursor()
238
+ cur.execute("SELECT actor FROM subscriptions WHERE event_topic = ?", (event_topic,))
239
+ return [row[0] for row in cur.fetchall()]
240
+
241
+ def get_state(self) -> Dict[str, Any]:
242
+ mailboxes: Dict[str, List[Dict[str, Any]]] = {}
243
+ subscriptions: Dict[str, List[Dict[str, Any]]] = {}
244
+ metadata: Dict[str, Any] = {}
245
+
246
+ with self.get_connection() as conn:
247
+ cur = conn.cursor()
248
+ cur.execute("SELECT * FROM messages ORDER BY created_at ASC")
249
+ for row in cur.fetchall():
250
+ to_act = row["to_actor"]
251
+ if to_act not in mailboxes:
252
+ mailboxes[to_act] = []
253
+ try:
254
+ payload = json.loads(row["payload"])
255
+ except Exception as err:
256
+ _ = err
257
+ payload = row["payload"]
258
+ mailboxes[to_act].append({
259
+ "id": row["id"],
260
+ "from_actor": row["from_actor"],
261
+ "to_actor": row["to_actor"],
262
+ "topic": row["topic"],
263
+ "payload": payload,
264
+ "timestamp": row["timestamp"],
265
+ "read": bool(row["read"])
266
+ })
267
+
268
+ cur.execute("SELECT * FROM subscriptions")
269
+ for row in cur.fetchall():
270
+ ev_topic = row["event_topic"]
271
+ if ev_topic not in subscriptions:
272
+ subscriptions[ev_topic] = []
273
+ subscriptions[ev_topic].append({
274
+ "actor": row["actor"],
275
+ "handler": row["handler"],
276
+ "subscribed_at": row["subscribed_at"]
277
+ })
278
+
279
+ cur.execute("SELECT * FROM metadata")
280
+ for row in cur.fetchall():
281
+ metadata[row["key"]] = row["value"]
282
+
283
+ return {
284
+ "mailboxes": mailboxes,
285
+ "subscriptions": subscriptions,
286
+ "metadata": metadata
287
+ }
288
+
289
+ def check_health(self, timeout_sec: float = 300.0) -> Dict[str, Any]:
290
+ now_ts = time.time()
291
+ deadlocks_detected = False
292
+ warning = None
293
+
294
+ with self.get_connection() as conn:
295
+ cur = conn.cursor()
296
+ cur.execute("SELECT COUNT(DISTINCT to_actor) FROM messages")
297
+ active_actors_count = cur.fetchone()[0]
298
+
299
+ cur.execute("SELECT COUNT(*) FROM messages")
300
+ total_messages = cur.fetchone()[0]
301
+
302
+ cur.execute("SELECT COUNT(*) FROM messages WHERE read = 0")
303
+ unread_messages = cur.fetchone()[0]
304
+
305
+ cur.execute("SELECT MIN(created_at), id, to_actor FROM messages WHERE read = 0")
306
+ row = cur.fetchone()
307
+ oldest_unread_ts = row[0] if row else None
308
+ oldest_msg_id = row[1] if row else None
309
+ oldest_to_actor = row[2] if row else None
310
+
311
+ oldest_unread_age_sec = (now_ts - oldest_unread_ts) if oldest_unread_ts is not None else 0.0
312
+
313
+ if oldest_unread_age_sec > timeout_sec and unread_messages > 0:
314
+ deadlocks_detected = True
315
+ warning = (
316
+ f"Starvation/Deadlock timeout ceiling exceeded: unread message {oldest_msg_id} "
317
+ f"for actor '{oldest_to_actor}' has been waiting for {oldest_unread_age_sec:.1f}s (> {timeout_sec}s)."
318
+ )
319
+ elif unread_messages > 100 and active_actors_count >= 2:
320
+ deadlocks_detected = True
321
+ warning = f"High message backlog detected across multiple actors ({unread_messages} unread)."
322
+
323
+ return {
324
+ "status": "PASS" if not deadlocks_detected else "WARNING_DEADLOCK",
325
+ "active_actors": active_actors_count,
326
+ "total_messages": total_messages,
327
+ "unread_messages": unread_messages,
328
+ "oldest_unread_age_sec": round(oldest_unread_age_sec, 2),
329
+ "timeout_ceiling_sec": timeout_sec,
330
+ "deadlock_free": not deadlocks_detected,
331
+ "warning": warning
332
+ }
333
+
334
+
335
+ class RedisStorageBackend(StorageBackend):
336
+ """
337
+ Redis-backed distributed storage backend for Actor QA Message Broker.
338
+ Enables horizontal scaling across multiple worker pods in Kubernetes clusters.
339
+ """
340
+
341
+ def __init__(
342
+ self,
343
+ redis_url: Optional[str] = None,
344
+ client: Optional[Any] = None,
345
+ key_prefix: str = "synapse"
346
+ ):
347
+ self.key_prefix = key_prefix.rstrip(":")
348
+ self.redis_url = redis_url or os.environ.get("SYNAPSE_REDIS_URL")
349
+ self.client = client
350
+
351
+ if self.client is None:
352
+ import importlib.util
353
+ if importlib.util.find_spec("redis") is None:
354
+ raise RuntimeError(
355
+ "redis package is required for RedisStorageBackend. Install via: pip install redis"
356
+ )
357
+ import redis
358
+ url = self.redis_url or "redis://localhost:6379/0"
359
+ self.client = redis.Redis.from_url(url, decode_responses=True)
360
+
361
+ self.init_backend()
362
+
363
+ def _k(self, *parts: str) -> str:
364
+ return f"{self.key_prefix}:{':'.join(parts)}"
365
+
366
+ def init_backend(self) -> None:
367
+ if self.client and hasattr(self.client, "ping"):
368
+ try:
369
+ self.client.ping()
370
+ except Exception as err:
371
+ _ = err
372
+ sys.stderr.write(f"Notice: Redis backend ping failed ({err}).\n")
373
+
374
+ def save_message(
375
+ self,
376
+ msg_id: str,
377
+ from_actor: str,
378
+ to_actor: str,
379
+ topic: str,
380
+ payload_str: str,
381
+ now_iso: str,
382
+ now_epoch: float,
383
+ ) -> None:
384
+ msg_data = {
385
+ "id": msg_id,
386
+ "from_actor": from_actor,
387
+ "to_actor": to_actor,
388
+ "topic": topic,
389
+ "payload": payload_str,
390
+ "timestamp": now_iso,
391
+ "created_at": now_epoch,
392
+ "read": 0
393
+ }
394
+ self.client.set(self._k("msg", msg_id), json.dumps(msg_data))
395
+ self.client.rpush(self._k("mailbox", to_actor), msg_id)
396
+ self.client.sadd(self._k("actors"), to_actor)
397
+ self.client.sadd(self._k("all_msg_ids"), msg_id)
398
+
399
+ def fetch_messages(
400
+ self,
401
+ actor: str,
402
+ topic: Optional[str] = None,
403
+ mark_read: bool = True,
404
+ ) -> List[Dict[str, Any]]:
405
+ msg_ids = self.client.lrange(self._k("mailbox", actor), 0, -1) or []
406
+ messages: List[Dict[str, Any]] = []
407
+
408
+ for mid in msg_ids:
409
+ raw = self.client.get(self._k("msg", mid))
410
+ if not raw:
411
+ continue
412
+ try:
413
+ data = json.loads(raw)
414
+ except Exception as err:
415
+ _ = err
416
+ continue
417
+
418
+ if topic and data.get("topic") != topic:
419
+ continue
420
+
421
+ try:
422
+ payload = json.loads(data["payload"])
423
+ except Exception as err:
424
+ _ = err
425
+ payload = data.get("payload")
426
+
427
+ was_read = bool(data.get("read", 0))
428
+ if mark_read and not was_read:
429
+ data["read"] = 1
430
+ self.client.set(self._k("msg", mid), json.dumps(data))
431
+
432
+ messages.append({
433
+ "id": data["id"],
434
+ "from_actor": data["from_actor"],
435
+ "to_actor": data["to_actor"],
436
+ "topic": data["topic"],
437
+ "payload": payload,
438
+ "timestamp": data["timestamp"],
439
+ "read": True if mark_read else was_read
440
+ })
441
+
442
+ return messages
443
+
444
+ def save_subscription(
445
+ self,
446
+ actor: str,
447
+ event_topic: str,
448
+ handler: str,
449
+ subscribed_at: str,
450
+ ) -> int:
451
+ self.client.sadd(self._k("subscribers", event_topic), actor)
452
+ sub_info = json.dumps({"handler": handler, "subscribed_at": subscribed_at})
453
+ self.client.hset(self._k("sub_meta", event_topic), actor, sub_info)
454
+ return int(self.client.scard(self._k("subscribers", event_topic)))
455
+
456
+ def get_subscribers(self, event_topic: str) -> List[str]:
457
+ subs = self.client.smembers(self._k("subscribers", event_topic))
458
+ if not subs:
459
+ return []
460
+ return sorted([s if isinstance(s, str) else str(s) for s in subs])
461
+
462
+ def get_state(self) -> Dict[str, Any]:
463
+ mailboxes: Dict[str, List[Dict[str, Any]]] = {}
464
+ subscriptions: Dict[str, List[Dict[str, Any]]] = {}
465
+ metadata: Dict[str, Any] = {}
466
+
467
+ actors = self.client.smembers(self._k("actors")) or []
468
+ for act in actors:
469
+ mailboxes[act] = self.fetch_messages(act, mark_read=False)
470
+
471
+ sub_keys = self.client.keys(self._k("sub_meta", "*")) or []
472
+ for sk in sub_keys:
473
+ ev_topic = sk.split(":")[-1]
474
+ subscriptions[ev_topic] = []
475
+ meta_map = self.client.hgetall(sk) or {}
476
+ for act, val_str in meta_map.items():
477
+ try:
478
+ val = json.loads(val_str)
479
+ except Exception as err:
480
+ _ = err
481
+ val = {"handler": "default_handler", "subscribed_at": ""}
482
+ subscriptions[ev_topic].append({
483
+ "actor": act,
484
+ "handler": val.get("handler", "default_handler"),
485
+ "subscribed_at": val.get("subscribed_at", "")
486
+ })
487
+
488
+ return {
489
+ "mailboxes": mailboxes,
490
+ "subscriptions": subscriptions,
491
+ "metadata": metadata
492
+ }
493
+
494
+ def check_health(self, timeout_sec: float = 300.0) -> Dict[str, Any]:
495
+ now_ts = time.time()
496
+ all_ids = self.client.smembers(self._k("all_msg_ids")) or []
497
+ total_messages = len(all_ids)
498
+ unread_messages = 0
499
+ oldest_unread_age_sec = 0.0
500
+ oldest_msg_id = None
501
+ oldest_to_actor = None
502
+ oldest_ts = None
503
+
504
+ for mid in all_ids:
505
+ raw = self.client.get(self._k("msg", mid))
506
+ if not raw:
507
+ continue
508
+ try:
509
+ data = json.loads(raw)
510
+ except Exception as err:
511
+ _ = err
512
+ continue
513
+
514
+ if not data.get("read", 0):
515
+ unread_messages += 1
516
+ c_ts = data.get("created_at", now_ts)
517
+ if oldest_ts is None or c_ts < oldest_ts:
518
+ oldest_ts = c_ts
519
+ oldest_msg_id = mid
520
+ oldest_to_actor = data.get("to_actor")
521
+
522
+ if oldest_ts is not None:
523
+ oldest_unread_age_sec = now_ts - oldest_ts
524
+
525
+ actors = self.client.smembers(self._k("actors")) or []
526
+ active_actors_count = len(actors)
527
+
528
+ deadlocks_detected = False
529
+ warning = None
530
+ if oldest_unread_age_sec > timeout_sec and unread_messages > 0:
531
+ deadlocks_detected = True
532
+ warning = (
533
+ f"Starvation/Deadlock timeout ceiling exceeded: unread message {oldest_msg_id} "
534
+ f"for actor '{oldest_to_actor}' has been waiting for {oldest_unread_age_sec:.1f}s (> {timeout_sec}s)."
535
+ )
536
+ elif unread_messages > 100 and active_actors_count >= 2:
537
+ deadlocks_detected = True
538
+ warning = f"High message backlog detected across multiple actors ({unread_messages} unread)."
539
+
540
+ return {
541
+ "status": "PASS" if not deadlocks_detected else "WARNING_DEADLOCK",
542
+ "active_actors": active_actors_count,
543
+ "total_messages": total_messages,
544
+ "unread_messages": unread_messages,
545
+ "oldest_unread_age_sec": round(oldest_unread_age_sec, 2),
546
+ "timeout_ceiling_sec": timeout_sec,
547
+ "deadlock_free": not deadlocks_detected,
548
+ "warning": warning
549
+ }
550
+
551
+
552
+ class ActorQaBroker:
553
+ """
554
+ Asynchronous Actor Message Broker & Sharding Dispatcher.
555
+ Backed by SQLite WAL by default, or RedisStorageBackend in distributed environments.
556
+ """
557
+
558
+ def __init__(
559
+ self,
560
+ state_file: Optional[str] = None,
561
+ memory_bus: Optional[Any] = None,
562
+ use_memory_bus: bool = False,
563
+ backend: Optional[StorageBackend] = None,
564
+ redis_url: Optional[str] = None,
565
+ ):
566
+ self._bus_adapter = None
567
+ if use_memory_bus or memory_bus is not None:
568
+ try:
569
+ from core.adapters import BrokerMemoryBusAdapter
570
+ except ImportError:
571
+ from tools.core.adapters import BrokerMemoryBusAdapter
572
+ self._bus_adapter = BrokerMemoryBusAdapter(bus=memory_bus)
573
+
574
+ if state_file:
575
+ self.state_file = state_file
576
+ else:
577
+ repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
578
+ self.state_file = os.path.join(repo_root, ".agent_memory", "actor_broker.db")
579
+
580
+ # Initialize storage backend
581
+ if backend is not None:
582
+ self.backend = backend
583
+ elif redis_url or os.environ.get("SYNAPSE_REDIS_URL"):
584
+ self.backend = RedisStorageBackend(redis_url=redis_url)
585
+ else:
586
+ self.backend = SQLiteStorageBackend(self.state_file)
587
+
588
+ def _get_conn(self) -> sqlite3.Connection:
589
+ """Backward-compatibility SQLite connection accessor."""
590
+ if isinstance(self.backend, SQLiteStorageBackend):
591
+ return self.backend.get_connection()
592
+ conn = sqlite3.connect(self.state_file, timeout=60.0)
593
+ conn.execute("PRAGMA journal_mode=WAL;")
594
+ conn.execute("PRAGMA busy_timeout=60000;")
595
+ conn.row_factory = sqlite3.Row
596
+ return conn
597
+
598
+ def _init_db(self):
599
+ """Backward-compatibility database initialization."""
600
+ self.backend.init_backend()
601
+
602
+ @property
603
+ def state(self) -> Dict[str, Any]:
604
+ """Backward-compatibility dictionary property representing current state."""
605
+ if self._bus_adapter and hasattr(self._bus_adapter, "get_state"):
606
+ return self._bus_adapter.get_state()
607
+ return self.backend.get_state()
608
+
609
+ def send_message(self, from_actor: str, to_actor: str, topic: str, payload: Any) -> Dict[str, Any]:
610
+ """Sends a message to an actor's mailbox with atomic persistence."""
611
+ if self._bus_adapter:
612
+ return self._bus_adapter.send_message(from_actor, to_actor, topic, payload)
613
+
614
+ now_dt = datetime.now(timezone.utc)
615
+ now_iso = now_dt.isoformat()
616
+ now_epoch = now_dt.timestamp()
617
+ msg_id = f"msg_{uuid.uuid4().hex[:12]}"
618
+ payload_str = json.dumps(payload) if not isinstance(payload, str) else payload
619
+
620
+ self.backend.save_message(msg_id, from_actor, to_actor, topic, payload_str, now_iso, now_epoch)
621
+
622
+ return {
623
+ "status": "PASS",
624
+ "message_id": msg_id,
625
+ "from": from_actor,
626
+ "to": to_actor,
627
+ "topic": topic,
628
+ "timestamp": now_iso
629
+ }
630
+
631
+ def fetch_messages(self, actor: str, topic: Optional[str] = None, mark_read: bool = True) -> List[Dict[str, Any]]:
632
+ """Retrieves messages for an actor with optional topic filter and read marking."""
633
+ if self._bus_adapter:
634
+ return self._bus_adapter.fetch_messages(actor, topic=topic, mark_read=mark_read)
635
+ return self.backend.fetch_messages(actor, topic=topic, mark_read=mark_read)
636
+
637
+ def subscribe(self, actor: str, event_topic: str, handler: Optional[str] = None) -> Dict[str, Any]:
638
+ """Subscribes an actor to an event topic."""
639
+ if self._bus_adapter:
640
+ return self._bus_adapter.subscribe(actor, event_topic, handler=handler)
641
+
642
+ now_iso = datetime.now(timezone.utc).isoformat()
643
+ total_subs = self.backend.save_subscription(actor, event_topic, handler or "default_handler", now_iso)
644
+
645
+ return {
646
+ "status": "PASS",
647
+ "actor": actor,
648
+ "topic": event_topic,
649
+ "total_subscribers": total_subs
650
+ }
651
+
652
+ def publish(self, event_topic: str, payload: Any, sender: str = "system") -> Dict[str, Any]:
653
+ """Publishes an event to all subscribed actors atomically."""
654
+ if self._bus_adapter:
655
+ res = self._bus_adapter.publish(event_topic, payload, sender=sender)
656
+ return {
657
+ "status": "PASS",
658
+ "topic": event_topic,
659
+ "subscribers_notified": res.get("delivered_count", 0)
660
+ }
661
+
662
+ subs = self.backend.get_subscribers(event_topic)
663
+ delivered_count = 0
664
+ for target_actor in subs:
665
+ self.send_message(
666
+ from_actor=sender,
667
+ to_actor=target_actor,
668
+ topic=event_topic,
669
+ payload=payload
670
+ )
671
+ delivered_count += 1
672
+
673
+ return {
674
+ "status": "PASS",
675
+ "topic": event_topic,
676
+ "subscribers_notified": delivered_count
677
+ }
678
+
679
+ def dispatch_shards(self, suite_manifest_path: str, shard_count: int = 4,
680
+ worker_role: str = "test-runner", allow_mock: bool = False) -> Dict[str, Any]:
681
+ """Partitions test suite items across parallel worker actors.
682
+ Fails closed if the manifest is missing unless allow_mock is explicitly True."""
683
+ resolved = suite_manifest_path
684
+ if not os.path.isabs(resolved):
685
+ repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
686
+ cand = os.path.join(repo_root, resolved)
687
+ if os.path.exists(cand):
688
+ resolved = cand
689
+
690
+ test_items = []
691
+ if os.path.exists(resolved):
692
+ try:
693
+ with open(resolved, "r", encoding="utf-8") as f:
694
+ data = json.load(f)
695
+ if isinstance(data, list):
696
+ test_items = data
697
+ elif isinstance(data, dict):
698
+ test_items = data.get("tests") or data.get("test_cases") or []
699
+ except Exception as e:
700
+ sys.stderr.write(f"Notice: Could not parse manifest ({e}).\n")
701
+ if not allow_mock:
702
+ return {
703
+ "status": "FAIL",
704
+ "error": f"Failed to parse manifest: {e}",
705
+ "manifest": suite_manifest_path
706
+ }
707
+
708
+ if not test_items:
709
+ if not allow_mock:
710
+ return {
711
+ "status": "FAIL",
712
+ "error": f"Suite manifest not found or empty: {suite_manifest_path}",
713
+ "manifest": suite_manifest_path,
714
+ "total_tests": 0,
715
+ "shard_count": shard_count,
716
+ "shards": {}
717
+ }
718
+ test_items = [f"tests/suite_part_{i}.spec.ts" for i in range(1, 13)]
719
+
720
+ shards = {f"worker_{i+1}": [] for i in range(shard_count)}
721
+ for idx, item in enumerate(test_items):
722
+ worker_id = f"worker_{(idx % shard_count) + 1}"
723
+ shards[worker_id].append(item)
724
+
725
+ # Notify workers via messages
726
+ for worker_id, items in shards.items():
727
+ self.send_message(
728
+ from_actor="orchestrator",
729
+ to_actor=f"{worker_role}:{worker_id}",
730
+ topic="ASSIGN_SHARD",
731
+ payload={"shard_id": worker_id, "test_count": len(items), "tests": items}
732
+ )
733
+
734
+ return {
735
+ "status": "PASS",
736
+ "total_tests": len(test_items),
737
+ "shard_count": shard_count,
738
+ "shards": {w: len(items) for w, items in shards.items()},
739
+ "dispatched_to_role": worker_role
740
+ }
741
+
742
+ def check_health(self, timeout_sec: float = 300.0) -> Dict[str, Any]:
743
+ """Scans mailboxes for unread backlogs, starvation, and circular deadlock indicators.
744
+ Enforces timeout_sec ceiling on unread message age."""
745
+ if self._bus_adapter:
746
+ return self._bus_adapter.check_health()
747
+ return self.backend.check_health(timeout_sec=timeout_sec)
748
+
749
+
750
+ def main():
751
+ parser = argparse.ArgumentParser(description="Asynchronous Actor QA Message Broker")
752
+ parser.add_argument("--redis-url", help="Optional Redis connection URL for distributed backend")
753
+ subparsers = parser.add_subparsers(dest="subcommand", help="Subcommand to execute")
754
+
755
+ # send-message
756
+ sm_p = subparsers.add_parser("send-message", help="Send message to actor mailbox")
757
+ sm_p.add_argument("--from-actor", required=True, help="Sender actor role")
758
+ sm_p.add_argument("--to-actor", required=True, help="Recipient actor role")
759
+ sm_p.add_argument("--topic", required=True, help="Message topic")
760
+ sm_p.add_argument("--payload", required=True, help="JSON payload")
761
+
762
+ # fetch-messages
763
+ fm_p = subparsers.add_parser("fetch-messages", help="Fetch messages from mailbox")
764
+ fm_p.add_argument("--actor", required=True, help="Actor role name")
765
+ fm_p.add_argument("--topic", help="Optional topic filter")
766
+ fm_p.add_argument("--peek", action="store_true", help="Do not mark as read")
767
+
768
+ # subscribe
769
+ sub_p = subparsers.add_parser("subscribe", help="Subscribe actor to an event topic")
770
+ sub_p.add_argument("--actor", required=True, help="Subscriber actor role")
771
+ sub_p.add_argument("--event", required=True, help="Event topic name")
772
+ sub_p.add_argument("--handler", help="Optional handler name")
773
+
774
+ # publish
775
+ pub_p = subparsers.add_parser("publish", help="Publish event to subscribers")
776
+ pub_p.add_argument("--event", required=True, help="Event topic name")
777
+ pub_p.add_argument("--payload", required=True, help="JSON payload")
778
+
779
+ # dispatch-shards
780
+ ds_p = subparsers.add_parser("dispatch-shards", help="Dispatch test suite across shards")
781
+ ds_p.add_argument("--suite-manifest", required=True, help="Path to manifest JSON")
782
+ ds_p.add_argument("--shard-count", type=int, default=4, help="Number of shards")
783
+ ds_p.add_argument("--worker-role", default="test-runner", help="Target worker role")
784
+ ds_p.add_argument("--allow-mock", action="store_true", help="Allow synthetic fallback if manifest missing")
785
+
786
+ # check-health
787
+ ch_p = subparsers.add_parser("check-health", help="Check broker health and deadlocks")
788
+ ch_p.add_argument("--timeout-sec", type=float, default=300.0, help="Timeout ceiling in seconds")
789
+
790
+ args = parser.parse_args()
791
+ broker = ActorQaBroker(redis_url=getattr(args, 'redis_url', None))
792
+
793
+ if args.subcommand == "send-message":
794
+ try:
795
+ payload = json.loads(args.payload)
796
+ except Exception as err:
797
+ _ = err
798
+ payload = args.payload
799
+ res = broker.send_message(args.from_actor, args.to_actor, args.topic, payload)
800
+ print(json.dumps(res, indent=2))
801
+ sys.exit(0)
802
+
803
+ elif args.subcommand == "fetch-messages":
804
+ msgs = broker.fetch_messages(args.actor, topic=args.topic, mark_read=not args.peek)
805
+ print(json.dumps(msgs, indent=2))
806
+ sys.exit(0)
807
+
808
+ elif args.subcommand == "subscribe":
809
+ res = broker.subscribe(args.actor, args.event, handler=args.handler)
810
+ print(json.dumps(res, indent=2))
811
+ sys.exit(0)
812
+
813
+ elif args.subcommand == "publish":
814
+ try:
815
+ payload = json.loads(args.payload)
816
+ except Exception as err:
817
+ _ = err
818
+ payload = args.payload
819
+ res = broker.publish(args.event, payload)
820
+ print(json.dumps(res, indent=2))
821
+ sys.exit(0)
822
+
823
+ elif args.subcommand == "dispatch-shards":
824
+ res = broker.dispatch_shards(
825
+ args.suite_manifest,
826
+ shard_count=args.shard_count,
827
+ worker_role=args.worker_role,
828
+ allow_mock=args.allow_mock
829
+ )
830
+ print(json.dumps(res, indent=2))
831
+ sys.exit(0 if res["status"] == "PASS" else 1)
832
+
833
+ elif args.subcommand == "check-health":
834
+ res = broker.check_health(timeout_sec=args.timeout_sec)
835
+ print(json.dumps(res, indent=2))
836
+ sys.exit(0 if res["status"] == "PASS" else 1)
837
+
838
+ else:
839
+ parser.print_help()
840
+ sys.exit(1)
841
+
842
+
843
+ if __name__ == "__main__":
844
+ main()