@teevee98/synapse-hub 0.0.0-stage → 3.8.3

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 +171 -0
  190. package/README.md +170 -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 +198 -0
  196. package/docs/ARCHITECTURE.md +199 -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 +174 -0
  200. package/docs/CLI_REFERENCE.md +176 -0
  201. package/docs/CONTRIBUTING.en.md +49 -0
  202. package/docs/CONTRIBUTING.md +49 -0
  203. package/docs/PERFORMANCE_AUDIT_REPORT.md +783 -0
  204. package/docs/PLUGIN_DEVELOPMENT_GUIDE.md +127 -0
  205. package/docs/QUALITY_GATES.en.md +118 -0
  206. package/docs/QUALITY_GATES.md +118 -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 +1358 -0
  212. package/docs/schemas/synapse.config.schema.json +86 -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 +31 -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 +2074 -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 +262 -0
  244. package/tools/api_drift_sentinel.py +208 -0
  245. package/tools/api_fuzzer.py +762 -0
  246. package/tools/author_integrity.py +190 -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 +2403 -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 +306 -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 +725 -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 +1271 -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,431 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
5
+
6
+ """
7
+ tools/core/adapters.py — Unified Memory Bus Bridges & Adapters
8
+ --------------------------------------------------------------
9
+ Provides bidirectional adapter bridges connecting specialized QA operating tools
10
+ (autogen_qa_broker, qa_event_stream, test_memory_os) directly to the unified SQLite
11
+ WAL-backed engine in tools/core/memory_bus.py:
12
+
13
+ 1. BrokerMemoryBusAdapter:
14
+ Adapts ActorQaBroker messaging & pub/sub to Partition 2 (actor_mailbox) & Partition 1 (blocks).
15
+ 2. EventStreamMemoryBusAdapter:
16
+ Adapts QaEventStream timeline logging, SHA-256 hash chaining & checkpoints to Partition 5 (event_stream).
17
+ 3. TestMemoryOSAdapter:
18
+ Adapts 3-tier TestMemoryOS (Core, Recall, Archival) to Partition 1 (blocks) & Partition 5 (event_stream).
19
+ """
20
+
21
+ import os
22
+ import sys
23
+ import json
24
+ import uuid
25
+ from datetime import datetime, timezone
26
+ from typing import Dict, Any, List, Optional
27
+
28
+ SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
29
+ TOOLS_DIR = os.path.dirname(SCRIPT_DIR)
30
+ for p in (SCRIPT_DIR, TOOLS_DIR):
31
+ if p not in sys.path:
32
+ sys.path.insert(0, p)
33
+
34
+ from memory_bus import UnifiedMemoryBus, get_memory_bus
35
+
36
+
37
+ class BrokerMemoryBusAdapter:
38
+ """Adapts ActorQaBroker interface to UnifiedMemoryBus (Partition 2 & 1)."""
39
+
40
+ def __init__(self, bus: Optional[UnifiedMemoryBus] = None):
41
+ self.bus = bus or get_memory_bus()
42
+
43
+ def send_message(
44
+ self,
45
+ from_actor: str,
46
+ to_actor: str,
47
+ topic: str,
48
+ payload: Any,
49
+ session_id: Optional[str] = None
50
+ ) -> Dict[str, Any]:
51
+ """Routes message directly to UnifiedMemoryBus mailbox partition."""
52
+ msg_id = self.bus.send_message(
53
+ sender=from_actor,
54
+ recipient=to_actor,
55
+ stage=topic,
56
+ payload=payload,
57
+ session_id=session_id
58
+ )
59
+ return {
60
+ "status": "PASS",
61
+ "message_id": msg_id,
62
+ "from": from_actor,
63
+ "to": to_actor,
64
+ "topic": topic,
65
+ "timestamp": datetime.now(timezone.utc).isoformat()
66
+ }
67
+
68
+ def fetch_messages(
69
+ self,
70
+ actor: str,
71
+ topic: Optional[str] = None,
72
+ mark_read: bool = True,
73
+ session_id: Optional[str] = None
74
+ ) -> List[Dict[str, Any]]:
75
+ """Fetches messages for recipient actor from UnifiedMemoryBus mailbox."""
76
+ raw_msgs = self.bus.receive_messages(
77
+ recipient=actor,
78
+ stage=topic,
79
+ mark_read=mark_read,
80
+ session_id=session_id
81
+ )
82
+ formatted = []
83
+ for m in raw_msgs:
84
+ formatted.append({
85
+ "id": m["message_id"],
86
+ "from_actor": m["sender"],
87
+ "to_actor": m["recipient"],
88
+ "topic": m["stage"],
89
+ "payload": m["payload"],
90
+ "timestamp": m["created_at"],
91
+ "read": True if mark_read else (m["status"] == "PROCESSED")
92
+ })
93
+ return formatted
94
+
95
+
96
+ def subscribe(self, actor: str, event_topic: str, handler: Optional[str] = None) -> Dict[str, Any]:
97
+ """Registers a pub/sub topic subscription using UnifiedMemoryBus memory_blocks."""
98
+ now_iso = datetime.now(timezone.utc).isoformat()
99
+ content = {
100
+ "actor": actor,
101
+ "event_topic": event_topic,
102
+ "handler": handler or "default_handler",
103
+ "subscribed_at": now_iso
104
+ }
105
+ self.bus.set_block(
106
+ label=f"{event_topic}:{actor}",
107
+ content=content,
108
+ scope="broker_subscriptions"
109
+ )
110
+ all_subs = self.bus.list_blocks(scope="broker_subscriptions")
111
+ total_topic_subs = sum(
112
+ 1 for b in all_subs if b.get("content", {}).get("event_topic") == event_topic
113
+ )
114
+ return {
115
+ "status": "PASS",
116
+ "actor": actor,
117
+ "topic": event_topic,
118
+ "total_subscribers": total_topic_subs
119
+ }
120
+
121
+ def publish(self, event_topic: str, payload: Any, sender: str = "system") -> Dict[str, Any]:
122
+ """Dispatches an event payload to all subscribed actors via UnifiedMemoryBus."""
123
+ all_subs = self.bus.list_blocks(scope="broker_subscriptions")
124
+ target_actors = [
125
+ b["content"]["actor"]
126
+ for b in all_subs
127
+ if isinstance(b.get("content"), dict) and b["content"].get("event_topic") == event_topic
128
+ ]
129
+ delivered_count = 0
130
+ for target in target_actors:
131
+ self.send_message(
132
+ from_actor=sender,
133
+ to_actor=target,
134
+ topic=event_topic,
135
+ payload=payload
136
+ )
137
+ delivered_count += 1
138
+ return {
139
+ "status": "PASS",
140
+ "topic": event_topic,
141
+ "delivered_count": delivered_count,
142
+ "target_actors": target_actors
143
+ }
144
+
145
+ def check_health(self) -> Dict[str, Any]:
146
+ """Returns health status of the broker backed by UnifiedMemoryBus."""
147
+ stats = self.bus.get_stats()
148
+ return {
149
+ "status": "PASS",
150
+ "backend": "UnifiedMemoryBus",
151
+ "mailbox_count": stats.get("actor_mailbox", 0),
152
+ "healthy": True
153
+ }
154
+
155
+ def get_state(self) -> Dict[str, Any]:
156
+ """Reconstructs state dictionary from UnifiedMemoryBus mailbox and subscriptions."""
157
+ mailboxes: Dict[str, List[Dict[str, Any]]] = {}
158
+ subscriptions: Dict[str, List[Dict[str, Any]]] = {}
159
+ metadata: Dict[str, Any] = {}
160
+
161
+ cur = self.bus._conn.cursor()
162
+ with self.bus._lock:
163
+ cur.execute("SELECT * FROM actor_mailbox ORDER BY created_at ASC")
164
+ for row in cur.fetchall():
165
+ to_act = row["recipient"]
166
+ if to_act not in mailboxes:
167
+ mailboxes[to_act] = []
168
+ try:
169
+ payload = json.loads(row["payload"])
170
+ except Exception:
171
+ payload = row["payload"]
172
+ mailboxes[to_act].append({
173
+ "id": row["message_id"],
174
+ "from_actor": row["sender"],
175
+ "to_actor": row["recipient"],
176
+ "topic": row["stage"],
177
+ "payload": payload,
178
+ "timestamp": row["created_at"],
179
+ "read": (row["status"] == "PROCESSED")
180
+ })
181
+
182
+ all_subs = self.bus.list_blocks(scope="broker_subscriptions")
183
+ for b in all_subs:
184
+ content = b.get("content", {})
185
+ if isinstance(content, dict):
186
+ ev_topic = content.get("event_topic", "")
187
+ if ev_topic not in subscriptions:
188
+ subscriptions[ev_topic] = []
189
+ subscriptions[ev_topic].append({
190
+ "actor": content.get("actor", ""),
191
+ "handler": content.get("handler", "default_handler"),
192
+ "subscribed_at": content.get("subscribed_at", b.get("updated_at", ""))
193
+ })
194
+
195
+ return {
196
+ "mailboxes": mailboxes,
197
+ "subscriptions": subscriptions,
198
+ "metadata": metadata
199
+ }
200
+
201
+
202
+ class EventStreamMemoryBusAdapter:
203
+ """Adapts QaEventStream interface to UnifiedMemoryBus (Partition 5: event_stream)."""
204
+
205
+ def __init__(self, bus: Optional[UnifiedMemoryBus] = None, session_id: Optional[str] = None):
206
+ self.bus = bus or get_memory_bus()
207
+ self.default_session_id = session_id or f"sess_{uuid.uuid4().hex[:8]}"
208
+
209
+ def _resolve_session(self, stream_file_or_session: str) -> str:
210
+ base = os.path.basename(stream_file_or_session)
211
+ name, _ = os.path.splitext(base)
212
+ return name if name else self.default_session_id
213
+
214
+ def init_stream(self, session_id: str, out_file: Optional[str] = None) -> Dict[str, Any]:
215
+ """Initializes a new event stream in the UnifiedMemoryBus."""
216
+ rec = self.bus.record_event(
217
+ session_id=session_id,
218
+ event_type="STREAM_INIT",
219
+ actor="system",
220
+ stage="INIT",
221
+ payload={"session_id": session_id, "initialized_at": datetime.now(timezone.utc).isoformat()}
222
+ )
223
+ return {
224
+ "status": "PASS",
225
+ "session_id": session_id,
226
+ "genesis_hash": rec["event_hash"],
227
+ "event_id": rec["event_id"],
228
+ "backend": "UnifiedMemoryBus"
229
+ }
230
+
231
+ def record_event(
232
+ self,
233
+ stream_file: str,
234
+ event_type: str,
235
+ actor: str,
236
+ payload: Any,
237
+ checkpoint_id: Optional[str] = None
238
+ ) -> Dict[str, Any]:
239
+ """Appends an event to the session stream in UnifiedMemoryBus."""
240
+ session_id = self._resolve_session(stream_file)
241
+ rec = self.bus.record_event(
242
+ session_id=session_id,
243
+ event_type=event_type,
244
+ actor=actor,
245
+ stage="STREAM",
246
+ payload=payload,
247
+ checkpoint_name=checkpoint_id
248
+ )
249
+ return {
250
+ "status": "PASS",
251
+ "session_id": session_id,
252
+ "event_type": event_type,
253
+ "event_hash": rec["event_hash"],
254
+ "sequence": rec["sequence"],
255
+ "checkpoint_name": checkpoint_id
256
+ }
257
+
258
+ def verify_stream(self, stream_file: str) -> Dict[str, Any]:
259
+ """Verifies cryptographic hash chain integrity in UnifiedMemoryBus."""
260
+ session_id = self._resolve_session(stream_file)
261
+ is_valid, err = self.bus.verify_stream_integrity(session_id)
262
+ events = self.bus.get_events(session_id)
263
+ if not is_valid:
264
+ return {
265
+ "status": "FAIL",
266
+ "valid": False,
267
+ "session_id": session_id,
268
+ "error": err
269
+ }
270
+ return {
271
+ "status": "PASS",
272
+ "valid": True,
273
+ "session_id": session_id,
274
+ "events_verified": len(events),
275
+ "last_hash": events[-1]["event_hash"] if events else None
276
+ }
277
+
278
+ def rollback(self, stream_file: str, to_checkpoint: str) -> Dict[str, Any]:
279
+ """Rolls back the session stream to the named checkpoint."""
280
+ session_id = self._resolve_session(stream_file)
281
+ rec = self.bus.rollback_to_checkpoint(session_id, to_checkpoint)
282
+ return {
283
+ "status": "PASS",
284
+ "session_id": session_id,
285
+ "rolled_back_to": to_checkpoint,
286
+ "rollback_event": rec
287
+ }
288
+
289
+ def replay_stream(self, stream_file: str, from_index: int = 0) -> List[Dict[str, Any]]:
290
+ """Replays events from sequence index."""
291
+ session_id = self._resolve_session(stream_file)
292
+ return self.bus.get_events(session_id, since_sequence=from_index)
293
+
294
+
295
+ class TestMemoryOSAdapter:
296
+ """Adapts TestMemoryOS interface to UnifiedMemoryBus (Partition 1: blocks & Partition 5: event_stream)."""
297
+ __test__ = False
298
+
299
+ def __init__(self, bus: Optional[UnifiedMemoryBus] = None):
300
+
301
+ self.bus = bus or get_memory_bus()
302
+
303
+ def update_core(self, block_key: str, data: Any) -> Dict[str, Any]:
304
+ """Stores key-value environment state into memory_blocks partition."""
305
+ now_iso = datetime.now(timezone.utc).isoformat()
306
+ res = self.bus.set_block(
307
+ label=block_key,
308
+ content=data,
309
+ scope="core_memory"
310
+ )
311
+ return {
312
+ "status": "PASS",
313
+ "block_key": block_key,
314
+ "updated_at": now_iso
315
+ }
316
+
317
+ def get_core(self, block_key: str) -> Optional[Dict[str, Any]]:
318
+ """Retrieves core memory block."""
319
+ block = self.bus.get_block(label=block_key, scope="core_memory")
320
+ if not block:
321
+ return None
322
+ return {
323
+ "block_key": block["label"],
324
+ "data": block["content"],
325
+ "updated_at": block["updated_at"]
326
+ }
327
+
328
+ def record_recall_step(
329
+ self,
330
+ session_id: str,
331
+ event_type: str,
332
+ actor: str,
333
+ payload: Any
334
+ ) -> Dict[str, Any]:
335
+ """Records an execution step into event_stream partition."""
336
+ rec = self.bus.record_event(
337
+ session_id=session_id,
338
+ event_type=event_type,
339
+ actor=actor,
340
+ stage="RECALL",
341
+ payload=payload
342
+ )
343
+ return {
344
+ "status": "PASS",
345
+ "session_id": session_id,
346
+ "sequence": rec["sequence"],
347
+ "event_id": rec["event_id"]
348
+ }
349
+
350
+ def get_recall_history(self, session_id: str, limit: int = 50) -> List[Dict[str, Any]]:
351
+ """Retrieves recent execution steps from event_stream."""
352
+ events = self.bus.get_events(session_id)
353
+ filtered = [
354
+ {
355
+ "id": e["sequence"],
356
+ "session_id": e["session_id"],
357
+ "event_type": e["event_type"],
358
+ "actor": e["actor"],
359
+ "payload": e["payload"],
360
+ "timestamp": e["timestamp"]
361
+ }
362
+ for e in events if e.get("stage") == "RECALL" or e.get("event_type") != "STREAM_INIT"
363
+ ]
364
+ return filtered[-limit:]
365
+
366
+ def archival_insert(self, key: str, payload: Any, aut_version: str = "v1.0") -> Dict[str, Any]:
367
+ """Inserts an archival record scoped by AUT release version."""
368
+ unique_label = f"{aut_version}:{key}:{uuid.uuid4().hex[:6]}"
369
+ self.bus.set_block(
370
+ label=unique_label,
371
+ content=payload,
372
+ scope=f"archival_{aut_version}",
373
+ tags=key
374
+ )
375
+ return {
376
+ "status": "PASS",
377
+ "key": key,
378
+ "aut_version": aut_version,
379
+ "label": unique_label
380
+ }
381
+
382
+ def archival_search(
383
+ self,
384
+ query: str,
385
+ aut_version: Optional[str] = None,
386
+ limit: int = 10
387
+ ) -> List[Dict[str, Any]]:
388
+ """Searches archival records matching query and optional aut_version."""
389
+ scope = f"archival_{aut_version}" if aut_version else None
390
+ blocks = self.bus.list_blocks(scope=scope)
391
+ matches = []
392
+ q_lower = query.lower()
393
+
394
+ for b in blocks:
395
+ text_repr = f"{b['label']} {json.dumps(b['content'], ensure_ascii=False)}".lower()
396
+ if q_lower in text_repr:
397
+ matches.append({
398
+ "key": b["tags"] or b["label"],
399
+ "aut_version": aut_version or b["scope"].replace("archival_", ""),
400
+ "payload": b["content"],
401
+ "updated_at": b["updated_at"]
402
+ })
403
+ if len(matches) >= limit:
404
+ break
405
+
406
+ return matches
407
+
408
+ def list_core(self) -> List[Dict[str, Any]]:
409
+ """Lists all core memory blocks from UnifiedMemoryBus."""
410
+ blocks = self.bus.list_blocks(scope="core_memory")
411
+ return [
412
+ {
413
+ "block_key": b["label"],
414
+ "data": b["content"],
415
+ "updated_at": b["updated_at"]
416
+ }
417
+ for b in blocks
418
+ ]
419
+
420
+ def gc(self, scrub_secrets: bool = True, max_age_days: int = 30) -> Dict[str, Any]:
421
+ """Executes garbage collection and returns bus status."""
422
+ stats = self.bus.get_stats()
423
+ return {
424
+ "status": "PASS",
425
+ "backend": "UnifiedMemoryBus",
426
+ "db_path": self.bus.db_path,
427
+ "blocks_count": stats.get("memory_blocks", 0),
428
+ "events_count": stats.get("event_stream", 0),
429
+ "secrets_scrubbed": 0
430
+ }
431
+
@@ -0,0 +1,263 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
3
+ # SPDX-License-Identifier: MIT
4
+ # Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
5
+
6
+ """
7
+ Synapse Hub — In-Flight Token Circuit Breaker & Model Cascade Engine
8
+ -------------------------------------------------------------------
9
+ Prevents runaway token spend, recursive agent loops, and cascading HTTP 429
10
+ rate limit lockouts across multi-agent executions.
11
+
12
+ Capabilities:
13
+ 1. Streaming Token Budget Sentinel:
14
+ - Enforces hard task-level and session-level token spend boundaries.
15
+ 2. Rate Limit & 429 Interceptor:
16
+ - Automatically monitors HTTP 429 quota exhaustion events.
17
+ 3. Dynamic Fallback Model Cascade:
18
+ - Cascades seamlessly across model tiers upon quota trip:
19
+ Tier 1 (Claude 3.7 Sonnet / Gemini Pro) -> Tier 2 (Gemini Flash) -> Local SLM.
20
+ 4. Automatic Half-Open Recovery:
21
+ - Probes downstream provider readiness after cooldown window.
22
+ """
23
+
24
+ import time
25
+ import threading
26
+ from enum import Enum
27
+ from typing import List, Dict, Any, Optional, Tuple
28
+ from contextlib import contextmanager
29
+
30
+
31
+ class CircuitBreakerState(str, Enum):
32
+ CLOSED = "CLOSED" # Normal operation, traffic allowed
33
+ OPEN = "OPEN" # Tripped, traffic blocked
34
+ HALF_OPEN = "HALF_OPEN" # Probing recovery after cooldown
35
+ FALLBACK = "FALLBACK" # Tripped primary, running on secondary fallback model
36
+
37
+
38
+ class CircuitBreakerError(Exception):
39
+ """Base exception for circuit breaker faults."""
40
+ pass
41
+
42
+
43
+ class TokenBudgetExceededError(CircuitBreakerError):
44
+ """Raised when token consumption exceeds maximum allowed budget."""
45
+ pass
46
+
47
+
48
+ class RateLimitExceededError(CircuitBreakerError):
49
+ """Raised when HTTP 429 quota exhaustion locks the circuit breaker."""
50
+ pass
51
+
52
+
53
+ DEFAULT_FALLBACK_MODELS = [
54
+ "claude-sonnet",
55
+ "gemini-pro",
56
+ "gemini-flash",
57
+ ]
58
+
59
+
60
+ class TokenCircuitBreaker:
61
+ """Enterprise in-flight token circuit breaker and automated model cascade controller."""
62
+
63
+ def __init__(
64
+ self,
65
+ task_token_budget: int = 200_000,
66
+ session_token_budget: int = 1_000_000,
67
+ rate_limit_threshold: int = 2,
68
+ fallback_models: Optional[List[str]] = None,
69
+ cooldown_seconds: float = 30.0,
70
+ ):
71
+ self.task_token_budget = task_token_budget
72
+ self.session_token_budget = session_token_budget
73
+ self.rate_limit_threshold = rate_limit_threshold
74
+ self.fallback_models = list(fallback_models or DEFAULT_FALLBACK_MODELS)
75
+ self.cooldown_seconds = cooldown_seconds
76
+
77
+ self.state = CircuitBreakerState.CLOSED
78
+ self.task_tokens = 0
79
+ self.session_tokens = 0
80
+ self.consecutive_429_count = 0
81
+ self.current_model_idx = 0
82
+ self.tripped_timestamp = 0.0
83
+ self.trip_reason = ""
84
+ self._lock = threading.Lock()
85
+
86
+ def get_active_model(self) -> str:
87
+ """Returns the currently active model from the fallback cascade."""
88
+ with self._lock:
89
+ if self.current_model_idx < len(self.fallback_models):
90
+ return self.fallback_models[self.current_model_idx]
91
+ return self.fallback_models[-1]
92
+
93
+ def can_execute(self) -> Tuple[bool, str]:
94
+ """
95
+ Evaluates whether an execution attempt is authorized.
96
+ Returns: (is_allowed, active_model_or_rejection_reason)
97
+ """
98
+ with self._lock:
99
+ if self.state == CircuitBreakerState.OPEN:
100
+ # Check if cooldown has elapsed to attempt HALF_OPEN probe
101
+ elapsed = time.time() - self.tripped_timestamp
102
+ if elapsed >= self.cooldown_seconds:
103
+ self.state = CircuitBreakerState.HALF_OPEN
104
+ return True, self._current_model_unlocked()
105
+ return False, f"Circuit breaker is OPEN ({self.trip_reason}). Cooldown: {int(self.cooldown_seconds - elapsed)}s remaining."
106
+
107
+ return True, self._current_model_unlocked()
108
+
109
+ def _current_model_unlocked(self) -> str:
110
+ if self.current_model_idx < len(self.fallback_models):
111
+ return self.fallback_models[self.current_model_idx]
112
+ return self.fallback_models[-1]
113
+
114
+ def record_tokens(self, count: int, model: Optional[str] = None) -> int:
115
+ """
116
+ Records consumed tokens and enforces budget limits.
117
+ Triggers model fallback cascade or trips to OPEN if budgets are violated.
118
+ """
119
+ if count <= 0:
120
+ return self.task_tokens
121
+
122
+ with self._lock:
123
+ if self.state == CircuitBreakerState.OPEN:
124
+ raise CircuitBreakerError(f"Cannot record tokens: Circuit breaker is OPEN ({self.trip_reason})")
125
+
126
+ self.task_tokens += count
127
+ self.session_tokens += count
128
+
129
+ # Enforce hard session-level budget
130
+ if self.session_tokens > self.session_token_budget:
131
+ self._trip_unlocked(f"Session token budget exceeded: {self.session_tokens} > {self.session_token_budget}")
132
+ raise TokenBudgetExceededError(self.trip_reason)
133
+
134
+ # Enforce task-level budget
135
+ if self.task_tokens > self.task_token_budget:
136
+ # Attempt to cascade to fallback model if available
137
+ if self.current_model_idx < len(self.fallback_models) - 1:
138
+ prev_model = self.fallback_models[self.current_model_idx]
139
+ self.current_model_idx += 1
140
+ new_model = self.fallback_models[self.current_model_idx]
141
+ self.state = CircuitBreakerState.FALLBACK
142
+ # Grant additional headroom for fallback model
143
+ self.task_token_budget += count
144
+ return self.task_tokens
145
+ else:
146
+ self._trip_unlocked(f"Task token budget exhausted: {self.task_tokens} > {self.task_token_budget} with no remaining fallback models")
147
+ raise TokenBudgetExceededError(self.trip_reason)
148
+
149
+ if self.state == CircuitBreakerState.HALF_OPEN:
150
+ self.state = CircuitBreakerState.CLOSED
151
+
152
+ return self.task_tokens
153
+
154
+ def record_http_status(self, status_code: int, error_message: str = "") -> Optional[str]:
155
+ """
156
+ Records HTTP response status code. If HTTP 429 (rate limit) is encountered,
157
+ triggers automated model cascade or trips breaker.
158
+ Returns the active fallback model name if cascade occurred, or None.
159
+ """
160
+ with self._lock:
161
+ if status_code == 429:
162
+ if self.state == CircuitBreakerState.HALF_OPEN:
163
+ self._trip_unlocked(f"Probe request failed in HALF_OPEN with HTTP 429: {error_message}")
164
+ raise RateLimitExceededError(self.trip_reason)
165
+
166
+ self.consecutive_429_count += 1
167
+ if self.consecutive_429_count >= self.rate_limit_threshold:
168
+ if self.current_model_idx < len(self.fallback_models) - 1:
169
+ self.current_model_idx += 1
170
+ self.consecutive_429_count = 0
171
+ self.state = CircuitBreakerState.FALLBACK
172
+ return self._current_model_unlocked()
173
+ else:
174
+ self._trip_unlocked(f"Rate limit (HTTP 429) threshold exceeded ({self.consecutive_429_count}): {error_message}")
175
+ raise RateLimitExceededError(self.trip_reason)
176
+ elif 200 <= status_code < 300:
177
+ self.consecutive_429_count = 0
178
+ if self.state == CircuitBreakerState.HALF_OPEN:
179
+ self.state = CircuitBreakerState.CLOSED
180
+ elif status_code >= 500 and self.state == CircuitBreakerState.HALF_OPEN:
181
+ self._trip_unlocked(f"Probe request failed in HALF_OPEN with HTTP {status_code}: {error_message}")
182
+ raise RateLimitExceededError(self.trip_reason)
183
+
184
+ return None
185
+
186
+ def trip(self, reason: str):
187
+ """Manually forces the circuit breaker into OPEN state."""
188
+ with self._lock:
189
+ self._trip_unlocked(reason)
190
+
191
+ def _trip_unlocked(self, reason: str):
192
+ self.state = CircuitBreakerState.OPEN
193
+ self.tripped_timestamp = time.time()
194
+ self.trip_reason = reason
195
+
196
+ def reset(self):
197
+ """Resets all token counters, error state, and restores CLOSED state."""
198
+ with self._lock:
199
+ self.state = CircuitBreakerState.CLOSED
200
+ self.task_tokens = 0
201
+ self.session_tokens = 0
202
+ self.consecutive_429_count = 0
203
+ self.current_model_idx = 0
204
+ self.tripped_timestamp = 0.0
205
+ self.trip_reason = ""
206
+
207
+ def get_status(self) -> Dict[str, Any]:
208
+ """Returns structured circuit breaker status."""
209
+ with self._lock:
210
+ return {
211
+ "state": self.state.value,
212
+ "active_model": self._current_model_unlocked(),
213
+ "active_model_index": self.current_model_idx,
214
+ "task_tokens": self.task_tokens,
215
+ "task_token_budget": self.task_token_budget,
216
+ "session_tokens": self.session_tokens,
217
+ "session_token_budget": self.session_token_budget,
218
+ "consecutive_429_count": self.consecutive_429_count,
219
+ "trip_reason": self.trip_reason,
220
+ "tripped_timestamp": self.tripped_timestamp,
221
+ }
222
+
223
+ @contextmanager
224
+ def protect_execution(self, estimated_tokens: int = 0):
225
+ """
226
+ Context manager that gates execution through circuit breaker and records tokens.
227
+ """
228
+ allowed, reason = self.can_execute()
229
+ if not allowed:
230
+ raise CircuitBreakerError(reason)
231
+ failed = False
232
+ try:
233
+ yield self.get_active_model()
234
+ except Exception:
235
+ failed = True
236
+ raise
237
+ finally:
238
+ if not failed and estimated_tokens > 0:
239
+ self.record_tokens(estimated_tokens)
240
+
241
+
242
+ # Global singleton instance for runtime interception
243
+ GLOBAL_CIRCUIT_BREAKER = TokenCircuitBreaker()
244
+
245
+
246
+ def record_tokens(count: int, model: Optional[str] = None) -> int:
247
+ return GLOBAL_CIRCUIT_BREAKER.record_tokens(count, model=model)
248
+
249
+
250
+ def record_http_status(status_code: int, error_message: str = "") -> Optional[str]:
251
+ return GLOBAL_CIRCUIT_BREAKER.record_http_status(status_code, error_message=error_message)
252
+
253
+
254
+ def can_execute() -> Tuple[bool, str]:
255
+ return GLOBAL_CIRCUIT_BREAKER.can_execute()
256
+
257
+
258
+ def get_active_model() -> str:
259
+ return GLOBAL_CIRCUIT_BREAKER.get_active_model()
260
+
261
+
262
+ def get_circuit_breaker() -> TokenCircuitBreaker:
263
+ return GLOBAL_CIRCUIT_BREAKER