konoha-mcp 2.2.23 → 2.2.25

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 (132) hide show
  1. package/NOTICE +14 -8
  2. package/README.md +20 -5
  3. package/apps/web/build/adapter-node.js +1 -1
  4. package/apps/web/build/build-meta.json +2 -2
  5. package/apps/web/build/client/_app/immutable/entry/{app.TYH87iYy.js → app.DtoBIrs4.js} +2 -2
  6. package/apps/web/build/client/_app/immutable/entry/app.DtoBIrs4.js.br +0 -0
  7. package/apps/web/build/client/_app/immutable/entry/app.DtoBIrs4.js.gz +0 -0
  8. package/apps/web/build/client/_app/immutable/nodes/{0.D7dPIEWA.js → 0.B8Iw7Xl1.js} +1 -1
  9. package/apps/web/build/client/_app/immutable/nodes/0.B8Iw7Xl1.js.br +0 -0
  10. package/apps/web/build/client/_app/immutable/nodes/{0.D7dPIEWA.js.gz → 0.B8Iw7Xl1.js.gz} +0 -0
  11. package/apps/web/build/client/_app/immutable/nodes/{13.TOXVaTBr.js → 13.CQB_Ed6W.js} +1 -1
  12. package/apps/web/build/client/_app/immutable/nodes/13.CQB_Ed6W.js.br +0 -0
  13. package/apps/web/build/client/_app/immutable/nodes/{13.TOXVaTBr.js.gz → 13.CQB_Ed6W.js.gz} +0 -0
  14. package/apps/web/build/client/_app/version.json +1 -1
  15. package/apps/web/build/client/_app/version.json.br +0 -0
  16. package/apps/web/build/client/_app/version.json.gz +0 -0
  17. package/apps/web/build/server/chunks/instance.js +3 -3
  18. package/apps/web/build/server/chunks/internal.js +1 -1
  19. package/apps/web/build/server/entries/pages/_layout.svelte.js +1 -1
  20. package/apps/web/build/server/entries/pages/_layout.svelte.js.map +1 -1
  21. package/apps/web/build/server/entries/pages/docs/_page.svelte.js +1 -1
  22. package/apps/web/build/server/entries/pages/docs/_page.svelte.js.map +1 -1
  23. package/apps/web/build/server/manifest-full.js +1 -1
  24. package/apps/web/build/server/manifest.js +1 -1
  25. package/apps/web/build/server/nodes/0.js +1 -1
  26. package/apps/web/build/server/nodes/13.js +1 -1
  27. package/apps/web/build/server/server.js +1 -1
  28. package/apps/web/package.json +1 -1
  29. package/assets/demo-agy.webp +0 -0
  30. package/assets/demo-claude.webp +0 -0
  31. package/assets/demo-codex.webp +0 -0
  32. package/assets/demo-commandcode.webp +0 -0
  33. package/assets/demo-cursor.webp +0 -0
  34. package/assets/demo-opencode.webp +0 -0
  35. package/assets/demo-pi.webp +0 -0
  36. package/assets/demo-skill-embed.webp +0 -0
  37. package/assets/demo-skills.webp +0 -0
  38. package/assets/demo-web.webp +0 -0
  39. package/assets/demo.webp +0 -0
  40. package/assets/konoha-akatsuki-flow.webp +0 -0
  41. package/assets/konoha-anbu-flow.webp +0 -0
  42. package/assets/konoha-flow-12-cli-upgrade-progress-engine.webp +0 -0
  43. package/assets/konoha-jonin-flow.webp +0 -0
  44. package/assets/konoha-kage-gate.webp +0 -0
  45. package/assets/konoha-langgraph-flow.webp +0 -0
  46. package/assets/konoha-orchestration-flow.webp +0 -0
  47. package/assets/konoha-qa-flow.webp +0 -0
  48. package/assets/konoha-telegram-flow.webp +0 -0
  49. package/assets/testing.webp +0 -0
  50. package/bin/commands/bridge.js +62 -4
  51. package/bin/commands/doctor.js +2 -0
  52. package/bin/commands/doctor_services.js +57 -0
  53. package/bin/commands/init.js +29 -8
  54. package/bin/commands/init_clients.js +95 -8
  55. package/bin/commands/init_migration.js +32 -1
  56. package/bin/lib/config_defaults.js +3 -0
  57. package/bin/lib/runtime_install.js +147 -54
  58. package/node_modules/jszip/package.json +2 -2
  59. package/node_modules/string_decoder/package.json +1 -1
  60. package/package.json +10 -3
  61. package/patches/gpt-tokenizer@4.1.0.patch +15 -0
  62. package/patches/jszip@3.10.2.patch +11 -0
  63. package/patches/string_decoder@1.3.0.patch +12 -0
  64. package/src/agent_contract.js +2 -2
  65. package/src/agent_deployer.js +48 -35
  66. package/src/agent_file_safety.js +57 -0
  67. package/src/antigravity_subagent_hook.js +30 -12
  68. package/src/bridge/gateway.js +2 -0
  69. package/src/bridge/gateway_adapters.js +155 -29
  70. package/src/bridge/handlers/anthropic.js +95 -26
  71. package/src/bridge/handlers/openai.js +18 -5
  72. package/src/bridge/sidecar/raw.js +10 -2
  73. package/src/bridge/stream_usage.js +66 -0
  74. package/src/chunin_knowledge_ddl.js +95 -0
  75. package/src/client_commands.js +190 -0
  76. package/src/db_bridges.js +53 -7
  77. package/src/db_schema.js +14 -2
  78. package/src/deploy_installer.js +212 -11
  79. package/src/deploy_utils.js +4 -0
  80. package/src/file_tools/common.js +65 -3
  81. package/src/file_tools_mcp.js +17 -9
  82. package/src/file_tools_router.js +67 -6
  83. package/src/global_skill_sync.js +3 -1
  84. package/src/mcp/chunin_knowledge.js +509 -0
  85. package/src/mcp/langgraph/edges/router.js +3 -0
  86. package/src/mcp/langgraph/index.js +22 -3
  87. package/src/mcp/langgraph/nodes/dispatch.js +3 -0
  88. package/src/mcp/langgraph/nodes/execute.js +87 -13
  89. package/src/mcp/langgraph/nodes/review.js +13 -1
  90. package/src/mcp/langgraph/slice_executor_registry.js +22 -0
  91. package/src/mcp/langgraph/state.js +5 -0
  92. package/src/mcp/lazy_subagent.js +11 -1
  93. package/src/mcp/memory_project_context.js +4 -1
  94. package/src/mcp/memory_subagent_runner.js +2 -1
  95. package/src/mcp/skills_common.js +1 -0
  96. package/src/mcp/subagent_spawner.js +7 -0
  97. package/src/mcp/todo_walkthrough_sync.js +7 -0
  98. package/src/mcp/tool_dispatch.js +18 -1
  99. package/src/mcp/web_search.js +27 -3
  100. package/src/mcp/workflow_completion_helpers.js +6 -1
  101. package/src/mcp/workflow_gates.js +118 -5
  102. package/src/mcp/workflow_sannin.js +9 -3
  103. package/src/mcp_clients/common.js +31 -0
  104. package/src/mcp_tool_manifest.json +36 -1
  105. package/src/pi_fs_helpers.js +31 -0
  106. package/src/pi_manager.js +68 -28
  107. package/src/provider_usage_logger.js +92 -0
  108. package/src/schema_ddl.js +17 -1
  109. package/src/templates/AGENTS.md +1 -1
  110. package/src/templates/GEMINI.md +1 -1
  111. package/src/templates/skills/chunin-skill/SKILL.md +34 -0
  112. package/src/templates/skills/chunin-skill/references/deep-research-analyst.md +27 -10
  113. package/src/templates/skills/kage-skill/SKILL.md +1 -1
  114. package/src/templates/skills/konoha/SKILL.md +23 -165
  115. package/src/templates/skills/konoha/references/contract.md +2 -2
  116. package/src/templates/skills/konoha/references/peragent-usage.md +1 -1
  117. package/src/token_usage.js +57 -0
  118. package/src/tools_savings_logger.js +26 -8
  119. package/src/url_canonical.js +58 -0
  120. package/src/vector_pipeline.js +6 -4
  121. package/src/vector_search.js +4 -2
  122. package/src/web/controllers/core_controller.js +10 -1
  123. package/src/workflow/jonin-builder/live_browser_monitor.js +23 -7
  124. package/apps/web/build/client/_app/immutable/entry/app.TYH87iYy.js.br +0 -0
  125. package/apps/web/build/client/_app/immutable/entry/app.TYH87iYy.js.gz +0 -0
  126. package/apps/web/build/client/_app/immutable/nodes/0.D7dPIEWA.js.br +0 -0
  127. package/apps/web/build/client/_app/immutable/nodes/13.TOXVaTBr.js.br +0 -0
  128. package/src/templates/skills/konoha/references/architecture.md +0 -99
  129. package/src/templates/skills/konoha/references/benchmark.md +0 -123
  130. package/src/templates/skills/konoha/references/docs.md +0 -46
  131. package/src/templates/skills/konoha/references/test.md +0 -71
  132. package/src/templates/skills/konoha/references/workflow.md +0 -104
@@ -69,6 +69,40 @@ Evaluate all discovered sources against the 4-tier credibility matrix:
69
69
  3. Explicitly report discrepancies, deprecated APIs, and version-specific divergences.
70
70
  4. Record exact versions, dates, and publication status for all referenced libraries.
71
71
 
72
+ ### SOP 4: Deep Research Loop (cache-first, batched)
73
+
74
+ Research runs cache-first so a repeated topic costs no network at all. The loop
75
+ follows the dzhng/deep-research shape, implemented in `src/mcp/chunin_knowledge.js`.
76
+
77
+ 1. **Retrieve before searching.** Query the local `chunin_knowledge` store for the
78
+ **top 5** references relevant to the topic (`retrieveRelevant`, hybrid FTS5 +
79
+ vector + cross-encoder rerank). Seed `visitedUrls` and `learnings` from them.
80
+ Skip this only when `use_knowledge_cache: false`.
81
+ 2. **Search only for what is new.** Call `web_search` with `exclude_urls` set to the
82
+ retrieved canonical URLs and take the **top 3** net-new results. URLs are
83
+ canonicalized (scheme forced to https, host lowercased, `utm_*`/`fbclid`/`gclid`
84
+ dropped, query sorted, trailing slash and `index.html` removed), so one page
85
+ reached by two spellings is fetched once.
86
+ 3. **Deduplicate before storing.** A learning is dropped when its `content_hash`
87
+ matches an existing one, when its canonical URL is already known, or when its
88
+ embedding scores `>= 0.90` cosine against a known learning. That cosine is
89
+ computed on **mean-centered** vectors: the embedder's raw cosine rates two
90
+ unrelated sentences at ~0.997, so the raw value cannot separate duplicates from
91
+ distinct claims.
92
+ 4. **Store in one batched write.** Surviving learnings are embedded with a single
93
+ `embedBatch` call (batched ONNX inference, length-sorted so padding is not
94
+ wasted) and inserted in one transaction with a prepared statement.
95
+ 5. **Recurse.** `breadth` (default 3, max 5) queries per level, `depth` (default 2,
96
+ max 3) levels, with `nextBreadth = ceil(breadth / 2)`. Learnings, follow-up
97
+ questions and visited URLs accumulate across levels; raw page bodies are
98
+ discarded after extraction.
99
+ 6. **Report.** `output_mode: "report"` keeps citations and follow-ups;
100
+ `"concise"` returns the learnings alone.
101
+
102
+ A store that was never embedded still answers: retrieval falls back to FTS, then to
103
+ the most recent rows for the topic, and storage keeps the text without a vector
104
+ when the semantic runtime is unavailable. Degrade, never fail.
105
+
72
106
  ### SOP 4: Cited Technical Intel Report Schema
73
107
  Deliver research findings structured in the standardized format:
74
108
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: deep-research-analyst
3
3
  description: "Expert guide for autonomous deep research, iterative web search, citation verification, evidence graph synthesis, and hallucination mitigation / Panduan ahli riset mendalam otonom, pencarian web iteratif, verifikasi sitasi, dan mitigasi halusinasi."
4
- author: vibes-plug-swarm
4
+ author: vibes-plug-swarm
5
5
  version: "3.0.0"
6
6
  ---
7
7
 
@@ -110,16 +110,33 @@ async def deep_research(query: str) -> list[ResearchFinding]:
110
110
  ```
111
111
 
112
112
  #### 3. Vector Store Caching for Intermediate Results
113
- Caching intermediate research results in vector stores prevents redundant crawling and accelerates knowledge retrieval:
114
- - **Storage:** Use `pgvector` or local `FAISS` for caching crawled page embeddings.
115
- - **Deduplication:** Deduplicate sources via cosine similarity before processing.
116
- - **Invalidation:** Implement TTL-based cache invalidation for time-sensitive research (e.g., fast-moving API docs).
113
+ Caching intermediate research results prevents redundant crawling and accelerates
114
+ retrieval. Konoha implements this locally in `src/mcp/chunin_knowledge.js` — no
115
+ pgvector, no FAISS, no API key:
116
+
117
+ - **Storage:** the `chunin_knowledge` table (schema v11) with an FTS5 index and a
118
+ 384-dim FLOAT32 `embedding` column registered through the bundled
119
+ `sqlite-vector` extension (`vector_init`, distance COSINE, normalized).
120
+ - **Retrieval order:** **top-5** stored references for the topic (FTS5 + vector +
121
+ cross-encoder rerank) before any network call; then **top-3** net-new web
122
+ results via `web_search({ exclude_urls })`.
123
+ - **Deduplication, three layers:** exact `content_hash`; canonical URL (tracking
124
+ params, trailing slash, scheme and host case normalized); and cosine `>= 0.90`
125
+ over **mean-centered** embeddings. Centering matters: the raw embedder rates two
126
+ unrelated sentences at ~0.997 cosine, so an uncentered threshold marks everything
127
+ as a duplicate. Measured after centering, unrelated pairs fall to -0.46..0.41 and
128
+ identical text stays at 1.0.
129
+ - **Bulk write:** surviving learnings are embedded in one batched `embedBatch` call
130
+ (real ONNX batching, length-sorted to avoid padding waste) and inserted in a
131
+ single transaction with a prepared statement.
132
+ - **Invalidation:** `last_verified_at` is per row; refresh it when a learning is
133
+ re-confirmed. Time-sensitive topics should re-search rather than trust the cache.
117
134
  - **Example Flow:**
118
- ```python
119
- # Store page chunks in vector store
120
- vector_store.add_texts(chunks, metadata=[{"url": url, "timestamp": now}])
121
- # Retrieve similar past findings
122
- cached = vector_store.similarity_search(query, k=3, filter={"ttl_valid": True})
135
+ ```js
136
+ const { retrieveRelevant, storeLearnings } = require('./mcp/chunin_knowledge');
137
+ const known = await retrieveRelevant({ topic, topK: 5 });
138
+ const fresh = await web_search({ query: topic, exclude_urls: known.map(r => r.canonical_url) });
139
+ await storeLearnings({ topic, learnings: fresh });
123
140
  ```
124
141
 
125
142
  #### 4. Episodic Research Memory
@@ -36,7 +36,7 @@ In the Konoha workflow, Kage exercises executive technical authority across two
36
36
  - **Two-Step Zero-AI-Slop Review (TARGET 100/100)**:
37
37
  - **Step 1 — `aislop_scan`**: Scans changed files via CLI `rtk aislop scan --changes` (or MCP tool with explicit paths). Zero findings of any severity are permitted.
38
38
  - **Step 2 — `anti-slop` Rule Review**: Loads the vendored `antislop` skill via `konoha.get_skill("antislop")` and verifies adherence to craftmanship standards and Delivery Gate rules.
39
- - **Socket Supply Chain Security Gate**: When maintaining Konoha itself, Kage verifies that `rtk socket ci` or `rtk socket scan create ./package.json --report` is 100% clean of High and Medium risk alerts (0 High/Error, 0 Medium/Warn).
39
+ - **Supply Chain Dependency Audit Gate**: When maintaining Konoha itself, Kage verifies that `rtk node tests/test_dependency_audit.js` passes: `pnpm audit --json` over the root and `apps/web` workspaces with zero unapproved advisories, no Socket account or token involved. The optional Socket.dev scan (`rtk node scripts/socket_audit_optional.js`, needs `SOCKET_CLI_API_TOKEN`) is advisory only and its `SKIPPED`/`UNVERIFIED` output is never a delivery blocker.
40
40
  - **Test Directory Discovery & Single-Directory Invariant**: Explore existing test directories (`tests/`, `test/`, `spec/`) using `find_files_clean`. Always place new tests within the established directory. NEVER create duplicate or conflicting test folders.
41
41
  - **Workspace Hygiene & Post-Approval Cleanup**: All temporary debug scripts (`debug_*`, `temp_*`, `test_patch.py`, `scratch/*`) must be removed upon final approval so the repository remains production-clean.
42
42
 
@@ -1,21 +1,20 @@
1
1
  ---
2
2
  name: konoha
3
- description: Guidelines and instructions for maintaining, extending, and debugging the Konoha MCP Tools Orchestrator, MCP middleware, and multi-archetype website builder across 8 coding clients (Antigravity IDE/CLI, Cursor, Claude Code, OpenCode, Command Code, Codex, Pi/pi.dev, OMP).
3
+ description: Runtime guide for the Konoha MCP Tools Orchestrator across 8 coding clients (Antigravity IDE/CLI, Cursor, [CC], OpenCode, Command Code, Codex, Pi/pi.dev, OMP) — contract, task format, tool block, and per-agent usage.
4
4
  tags:
5
5
  - konoha
6
6
  - orchestrator
7
7
  - mcp
8
- - maintenance
9
8
  - engineering
10
9
  - website-builder
11
10
  - fts5
12
11
  ---
13
12
 
14
- # 🍃 Konoha Maintenance & Engineering Skill (v2.2.23)
13
+ # 🍃 Konoha MCP Tools Orchestrator Skill (v2.2.25)
15
14
 
16
- Core operational guide for maintaining, extending, and debugging the **Konoha MCP Tools Orchestrator**, native Tree-sitter + FTS5 + Granite/MiniLM code-intelligence engine, and multi-agent coordination server.
15
+ Runtime guide for the **Konoha MCP Tools Orchestrator**, native Tree-sitter + FTS5 + Granite/MiniLM code-intelligence engine, and multi-agent coordination server.
17
16
 
18
- Konoha serves ALL 56 canonical tools through standard MCP protocols across 8 supported AI coding clients (Antigravity, Cursor, Claude Code, OpenCode, Command Code, Codex, Pi, OMP). All 56 canonical MCP tools (plus 2 hidden deprecated compatibility aliases, 58 total in manifest) are formally declared in `src/mcp_tool_manifest.json` and dispatched via `src/mcp/tool_dispatch.js` across 9 specialists:
17
+ Konoha serves ALL 56 canonical tools through standard MCP protocols across 8 supported AI coding clients (Antigravity, Cursor, [CC], OpenCode, Command Code, Codex, Pi, OMP). All 56 canonical MCP tools (plus 2 hidden deprecated compatibility aliases, 58 total in manifest) are formally declared in `src/mcp_tool_manifest.json` and dispatched via `src/mcp/tool_dispatch.js` across 9 specialists:
19
18
  - Deep Research (@chunin): Web research, documentation lookup, and evidence synthesis.
20
19
  - Code Exploration (@genin): Read-only codebase exploration, symbol search, and architecture review.
21
20
  - Architecture & Quality Gates (@kage): Architecture decisions, security audits, and delivery review gate.
@@ -28,171 +27,30 @@ Konoha serves ALL 56 canonical tools through standard MCP protocols across 8 sup
28
27
 
29
28
  ---
30
29
 
31
- ## 🔒 Cardinal Maintenance Invariants
30
+ ## 🔒 Working Rules
32
31
 
33
- 1. **Tool Boundaries & Global-Only Configs**:
34
- - Repository code search: ALWAYS use the native code intelligence tools (`code_search`, `code_symbol`, `code_impact`).
35
- - Skill lookup: ALWAYS use Konoha MCP (`konoha.find_skill`, `konoha.get_skill`).
36
- - Bounded file I/O: ALWAYS use Konoha bounded tools (`read_file_range`, `read_file_head`, `token_efficient_grep`).
37
- - Shell commands: ALWAYS prefix with RTK (`rtk <command>`).
38
- - Global-Only & Append-Only Client Configs: Never write `.omp`, `.codex`, `.cursor`, `.claude`, `.agents`, or `.gitignore` rules (such as `/PLAN.md` or `.omp/.`) into user project directories; all client configs live under user home (`~/.omp`, `~/.codex`, `~/.cursor`, `~/.config/git/ignore`, etc.) and use automatic date-stamped backups (`~/.konoha/backups/configs/<client>/<scope>/`) + syntax-aware append-only merging (`src/config_backup_manager.js`, `src/config_merger.js`) with ownership tracking (`~/.konoha/backups/ownership_manifest.json`). Konoha never deletes external `agents/` or `conversations/` directories.
39
- - Ownership-Aware Rsync-Like Global Skill Sync & Targeted Diff-and-Patch (`src/global_skill_sync.js`): all 17 canonical Konoha skills, their references (including the cross-framework Motion references `motion-nextjs`, `motion-nuxt`, `motion-svelte`, `motion-angular`, `framer-motion-animator` under `jonin-skill`), and `SOUL.md` are synchronized across the ten global skill directories of the eight supported clients (`~/.agents/skills`, `~/.gemini/antigravity-cli/skills`, `~/.gemini/skills`, `~/.cursor/skills`, `~/.claude/skills`, `~/.config/opencode/skills`, `~/.commandcode/skills`, `~/.codex/skills`, `~/.pi/agent/skills`, `~/.omp/agent/skills`). The source is `src/templates/skills`; `~/.agents/skills` is a deployed mirror, while this repository tracks its own `.agents/skills/` and pins it byte-identical to the templates. Fresh installs skip pre-existing user files (`--ignore-existing`), upgrades apply targeted line diff-and-patch updates (`computeLineDiffPatch` / `applyTargetedTextPatch`) while preserving user customizations, and a file recorded as `created_by_konoha` with no user keys is replaced wholesale instead of being left stale.
40
- - No Filesystem Mirrors: Konoha does not maintain filesystem mirrors of client skills; synchronization is targeted line diff-and-patch in place. Outside this repository no tracked copy of a skill exists: deployed copies live under the user's home. The one tracked duplicate is this repo's `.agents/skills/`, held byte-identical to `src/templates/skills` by `tests/test_skill_tree_parity.js`.
41
- - Scoped Execution & External Skill RAG Integration: Hooks and tool blockers activate only inside Konoha-managed contexts (`/konoha <prompt>` or `/<subagent-name> <prompt>`). External global and project-level skills across all 8 harnesses are indexed in-place into the existing SQLite Project Knowledge RAG (`~/.konoha/konoha.db`) with strict project isolation (`isPathVisible`) so project skills never leak across workspaces.
42
- - Project Skills Outrank the Index: `getSkillReadRoots()` (`src/mcp/skills_common.js`) resolves the project's own tree — `.agents/skills` and the sixteen `PROJECT_SKILL_SUBDIRS` — ahead of client mirrors, and `findSkill`/`listSkills` merge those rows with the database. Never make a project migrate before its skills are usable, and never let a Konoha skill shadow a project skill of the same name. `tests/test_project_skills_dual_source.js` is the guard.
43
- - Extension Isolation: The obsolete `andycungkrinx91.konoha-bridge-master-universal` extension directory is eliminated; all IDEs use direct MCP configuration.
44
- 2. **Quality & Security Delivery Gate**:
45
- - Shipped code must pass `rtk npx aislop scan --changes` with score **100/100 Healthy**, 0 errors, and 0 warnings.
46
- - Final Kage review requires `confidence >= 98%`, `ai_slop_clean: true`, and zero security findings.
47
- 3. **Source File Line Limit**: Keep all `.js`, `.py`, and `.svelte` source files strictly under 700 lines (`scripts/lint.js`).
48
- 4. **Draw.io Zero Collision Rule**: Never introduce overlapping cells or bounding-box collisions in Draw.io diagram pages (`tests/test_diagram_sync.js`).
49
- 5. **Single-Source Version Synchronization**: Keep all 18 managed repository targets strictly synchronized via `scripts/bump_version.js`. The manifest is the source of truth — read the count from `rtk node scripts/bump_version.js --check`, never hardcode it in prose or code. `src/templates/skills/konoha/SKILL.md` is not a managed target, so this skill's own title is edited by hand.
50
- 6. **Release Governance**: When maintaining or updating Konoha on branch `master`, ensure all discovered tests pass before release commits.
51
- 7. **Token Savings Flow Logic Preservation Invariant**: Never modify or disrupt the token savings telemetry flow logic. In `src/tools_savings_logger.js`, baseline bytes for `find_skill` / `find_skills` are dynamically computed from the actual `SUM(byte_size)` of retrieved skill candidates in SQLite FTS5 matching, authentically reflecting 83%–98% context savings.
52
- 8. **Schema Version Is Not the App Version**: `src/db_schema.js` owns `CURRENT_SCHEMA_VERSION` (9 today), the shipped `PRAGMA user_version` write, and the canonical 45 raw / 33 declared table list. Never reintroduce a version-derived schema constant — a `TARGET_SCHEMA_VERSION = 2218` once shipped and was removed in 2.2.18. `konoha doctor` reports `schema 9` and `app 2.2.23` separately and warns on drift; `tests/test_schema_migrations_and_lifecycle.js` fails if a second writer appears or the table count moves.
53
- 9. **Red-Skill Isolation Fails Closed**: `src/skill_authorization.js` classifies a skill by exact canonical name → `RED_SKILL_ROOT_PATTERN` (`^(?:akatsuki-skill)(?:[-_/@]|$)`) → legacy pattern → tags, and `src/mcp/skills_retrieval.js` resolves the row before authorizing it. Lab databases are rejected when they alias the main DB (same path, symlink, dangling symlink, hardlink), and any `stat` error other than `ENOENT`/`ENOTDIR` raises `LAB_DB_ISOLATION_VIOLATION` (`src/db.js`). Never widen those predicates "to be tolerant": this gate is what stops offensive tooling loading outside the sandbox.
54
- 10. **Cyber Pack Is Opt-In, Never Bundled**: the pack is downloaded only via `konoha akatsuki cyber-pack install --confirm`, sha256-verified, extracted under `~/.konoha/akatsuki-lab/cyber-pack/`, and indexed as `akatsuki-skill` references. `src/cyber_pack.js#remove` must keep using the deduped union of `bin/lib/paths.js#DEFAULT_SKILLS_DIRS` and `src/global_skill_sync.js#getGlobalHarnessSkillTargets`; the two lists still differ (the search list keeps the legacy `~/.opencode/skills`), and hardcoding either one is the bug that left copies behind.
55
- 11. **Migration Runs In-Process**: every caller awaits `runMigration({...})` from `src/migrate` — `bin/lib/install_lifecycle.js`, `bin/lib/runtime_lifecycle.js`, `bin/commands/migrate.js`, `bin/commands/upgrade.js`, `bin/commands/init_migration.js`, `bin/commands/doctor_services.js`, `src/skill_manager.js`, `src/web/controllers/skills_controller.js`. Never restore `spawnSync(process.execPath, [...migrate.js...])`: it hid every failure behind `status !== 0`. Success returns `{ ok: true, indexed, deferredSkills, dbPath }`; incomplete required skills return `{ ok: false, reason: 'required_skills_missing', missingRequired, remainingLegacy }`. Only `main()` exits the process.
56
- 12. **Time Budgets Come From Config**: `bin/lib/config_defaults.js` holds the shipped defaults as code (70 keys, including `migrate_time_budget_seconds` 900, `install_build_migrate_timeout_ms` 900000, and the `mcp_orphan_parent_poll_ms` / `mcp_stdio_idle_timeout_ms` / `mcp_daemon_superseded_poll_ms` orphan-guard polls) so an upgrade never rewrites the user's `~/.konoha/config.json`; `bin/lib/paths.js` derives `MIGRATION_TIMEOUT_MS` / `INSTALL_BUILD_MIGRATE_TIMEOUT_MS` from them. No `timeout: 900000` literal may reappear on the install path (`tests/test_config_centralization.js`, `tests/test_upgrade_timeout_budgets.js`).
57
- 13. **Mirrored Modules Load Config Through `src/config_access.js`**: `copyRuntimeConfigFiles` mirrors top-level `src/*.js` flat into `~/.konoha/`, so `require('../bin/lib/paths')` escapes to `~/bin/lib/paths` at runtime. Any `src/` module that may execute from the mirror must go through `config_access`, which tries `../bin/lib`, `./bin/lib`, `../../bin/lib`.
58
- 14. **Upgrade Success Requires PATH Agreement**: `konoha upgrade` runs the PATH-resolved `konoha --version` and compares it with the installed package (`bin/lib/upgrade_verify.js`). A missing binary, a rename, or output without a version line exits `1`. Never restore the old "located package root equals itself" comparison, which printed success while `konoha version` reported the previous release.
59
- 15. **No Install Scripts**: `postinstall` is deleted (npm aborts stock installs with `EALLOWSCRIPTS`). The supported flow is `npm install -g konoha-mcp` → `konoha init --yes` or `konoha upgrade`. `tests/test_postinstall_contract.js` no longer exists — do not cite or recreate it.
60
- 16. **The Token Governor Bounds Konoha's Own Graph, Not the Harness**: `src/mcp/langgraph/token_guard.js` accepts `ALLOWED_CEILINGS = [8192, 16384, 32768, 65536]`, defaults to 8192, and rounds invalid input up to the nearest allowed value. It clamps what Konoha hands the model *inside its internal LangGraph*. It does not budget harness model context. Never cite `8192` as a whole-session token ceiling.
61
- 17. **Two Databases, No Cross-Joins**: app data lives in `~/.konoha/konoha.db` (`src/db.js`); Akatsuki lab data lives in `~/.konoha/akatsuki-lab/lab.db` via `openLabDb()` (`src/workflow/akatsuki/lab_db.js`). A lab path handed to the main opener throws `LAB_DB_ISOLATION_VIOLATION`; `kali_tools` is created only by the lab opener, and no SQL may join the two databases — join in application code. Guards: `tests/test_akatsuki_lab_isolation_section_i.js`, `tests/test_akatsuki_skill_authz_db_isolation.js`.
62
- 18. **First-Run Login Opens on Set-New-Password**: while `GET /api/v1/auth/status` returns `is_bootstrap: true`, the web UI renders the setup form (`data-testid="first-run-setup-form"`) from `authState.isBootstrap`; never branch on a hardcoded `konohagakure` comparison. The 403 `requires_password_change` gate in `src/web_server.js` and the bootstrap password value in `src/auth.js` stay unchanged. Guard: `tests/e2e/login_default_password_redirect.spec.js`.
63
- 19. **A Server Nobody Owns Must Exit**: `src/mcp_orphan_guard.js` gives both long-lived entry points a self-terminating path. `startStdioOrphanGuard` polls `process.ppid === 1` every `mcp_orphan_parent_poll_ms` (30 s; `KONOHA_MCP_ORPHAN_POLL_MS` is a test seam, not user config) and exits when the spawning client died, so a stdio server orphaned by a short-lived launcher does not hold the bridge port or the database; `noteActivity()` on every `readline` line feeds a `mcp_stdio_idle_timeout_ms` (4 h; `KONOHA_MCP_STDIO_IDLE_MS`, same seam) idle budget, which is the only exit Windows has because Windows does not reparent children and `ppid` never becomes 1 there. `startDaemonOrphanGuard` claims `bridge.pid` and exits when a newer live daemon takes it over. Never remove the guard to "simplify startup": stdin EOF is not a reliable exit signal (a launcher that exits tears down its own pipe), so the poll is the only path that survives a reparent. Guards: `tests/test_mcp_orphan_guard.js`.
64
- 20. **The Web UI Starts Only by Hand**: `konoha ui` exposes exactly `start` (foreground, blocking) and `build`. Nothing auto-starts it — not `init`, not `upgrade`, not the MCP stdio bootstrap. A second `konoha ui start` on a port that is already listening exits 1 with `already running`; `assertSingleInstance` probes the port before binding. Guard: `tests/test_ui_manual_only.js`.
32
+ 1. **Tool boundaries** — repository discovery through `code_search`/`code_symbol`/`code_impact`; skills through Konoha MCP (`find_skill`/`get_skill`); file I/O through the bounded tools (`read_file_range`, `read_file_head`, `token_efficient_grep`); every shell command behind RTK (`rtk <command>`).
33
+ 2. **Client configs are global-only and append-only** — config lives under `~/.<client>`, is backed up under `~/.konoha/backups/configs/<client>/<scope>/`, and is merged by `src/config_merger.js`. Never write `.omp`, `.codex`, `.cursor`, `.claude`, `.agents`, or `.gitignore` rules into a user project.
34
+ 3. **Message format** — every human and agent message uses `konoha/task-format`: `**Feedback` / `**Task` / `**Rules` in, `**Result` / `**Evidence` / `**Blockers` / `**Next` out.
35
+ 4. **HITL gates fail closed** — Gate 1 (`pending_plan_approval`) and Gate 2 (`pending_human_signoff`) render the picker on every client and submit the human's reply verbatim via `sannin({ task_dir, choice, refinement })`.
36
+ 5. **Resume safety** — on every new or resumed session, re-read the contract, repeat skill discovery, and restore the Konoha/RTK workflow before acting.
65
37
 
66
- 21. **A Delivery Verdict Needs All Three Local Cross-Platform CI Environments**: cross-platform end-to-end verification is mandatory, never optional. A change counts as done only after Linux, Windows, and macOS all pass — a single-OS green is not a verdict. Exercise all 3 local cross-platform CI test environments before handoff: (1) **Linux**: Debian clean-room `pnpm test:sandbox [-- --shard=I/8]` + Ubuntu `act` `pnpm ci:act` / `pnpm ci:act:shard` (`act -j checks` / `act -j test --matrix os:ubuntu-latest --matrix shard:<N>`, `.actrc` pins `catthehacker/ubuntu:act-latest`); (2) **Windows**: `docker/windows-vm/oem/run-ci.cmd [-Shard I/N]` / `retest.cmd` inside `dockur/windows` (`scripts/windows-ci.ps1`; the guest runs the full suite in one pass by default — CI's shards parallelize 16 separate runners, so use `-Shard` to narrow one failure, not to reproduce the matrix); (3) **macOS**: `KONOHA_SANDBOX_RUNTIME=container pnpm test:sandbox [-- --shard=I/8]` via Apple `container`, plus native `macos-latest` CI (or the Linux symlinked-`HOME` proxy for `/var` → `/private/var` and APFS path checks in `docs/CI.md`). `.github/workflows/cross-platform.yml` also runs on push, PR, tag, manual dispatch, and nightly at 02:00 UTC.
38
+ ## 📚 Load On Demand
67
39
 
68
- 22. **No Dynamic Execution, Anywhere in the Runtime**: `src/`, `bin/`, and `scripts/` contain no `eval(`, no `new Function(`, no `Function('…')`, and no `node:vm` code generation. The generated guardrail hooks (`src/mcp_clients/command_code.js`, `src/mcp_clients/claude_code_hooks.js`, `src/pi_blocker_template.js`) embed `buildGuardrailCheckerSource()` verbatim as `const checkCommandGuardrails = function checkCommandGuardrails(command) {...}` — never wrap it in `new Function(source)()` and never `JSON.stringify` it into a string. `tests/test_no_dynamic_execution.js` scans every runtime file, then executes the generated hooks to prove deny/block/allow/unmanaged still behave.
69
- 23. **`lodash` Must Never Return (`patches/xlsx-populate@1.21.0.patch`)**: `xlsx-populate@1.21.0` is the only thing that ever pulled it, and its `template()` compiles strings with `Function`. The patch replaces all 19 `require("lodash")` sites with `lib/lodash-lite.js` (27 helpers, lodash-4 semantics) and deletes `browser/` (13.9 MiB webpack bundle, 52 `Function(` occurrences) plus `examples/` and the `browser` manifest field. Konoha resolves `main: lib/XlsxPopulate.js` only. Regenerating the patch from a fresh package loses the shim — `tests/test_xlsx_populate_lodash_lite.js` (74 semantics + XLSX round-trip) and `tests/test_dependency_posture.js` fail if it does.
70
- 24. **Patched and Bundled Dependencies Are Pinned Exactly**: `xlsx-populate`, `pptxgenjs`, `cfb`, `docx`, `playwright`, and `hash-wasm` carry exact versions (no `^`/`~`), and `.github/workflows/publish.yml` installs with `--frozen-lockfile`. A caret on a patched or bundled package lets the lockfile and the published tarball disagree about which bytes shipped. `tests/test_dependency_posture.js` enforces both.
71
- 25. **Images Enter the Presentation Engine as Buffers, Never Paths**: `pptxgenjs` turns `addImage({ path })` into `fs.readFileSync` and `{ path: 'http…' }` into an HTTPS GET. `src/workflow/tokubetsu-scribe/doc_engine_presentation.js` exposes `addInlineImage(slide, buffer)`, which requires an in-memory PNG (magic-byte checked) and emits a base64 data URI; it holds the file's only `addImage` call site. `tests/test_document_engine_security.js` fails if a second call site or a `path:` key appears.
72
- 26. **Socket Suppressions Are Narrowed, Never Widened**: `socket.yml` keeps `envVars`, `urlStrings`, `networkAccess`, `gptSecurity`, `gptAnomaly`, and `newAuthor` suppressed because those describe Konoha's documented contract. It must **not** suppress `usesEval` (nothing dynamic executes, and no patched package ships a browser bundle) and must **not** list `pnpm-lock.yaml` or `patches/**` in `projectIgnorePaths` (dependency and patch changes are exactly what needs auditing). Suppressing an alert is not a fix; it is a written claim that the capability is intended, and `tests/test_socket_security_audit.js` asserts the claim stays honest.
73
- 27. **The Per-Turn Prefix Is a Budget, Not a Dumping Ground**: what Konoha injects into a harness prompt is paid on *every* request, so it is governed like any other contract. `buildManagedContract` (`src/agent_contract.js`) removes **every** `KONOHA-CONTRACT-START`…`KONOHA-CONTRACT-END` span before writing the fresh block — splicing only the first pair left a second block forever, made redeploy a permanent no-op, and put two contract versions in one file. `buildOmpWorkflowAddendum` (`src/omp_manager.js`) carries *rules only*: framework scaffolding commands and scan-scoping procedure live in `jonin-skill` / `konoha` references, which load on demand. Only one user-level context file is injected per harness (`~/.omp/agent/AGENTS.md` shadows `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`, `~/.config/opencode/AGENTS.md`, `~/.agents/AGENTS.md` for OMP), and `~/.omp/AGENTS.md` is not a context file at all — the native user path is `~/.omp/agent/AGENTS.md`. Guards: `tests/test_lightweight_contracts.js` (addendum ≤ 4200 B, managed contract ≤ 5200 B, second deploy `changed: false`) and the duplicate-block regression in `tests/test_omp_manager.js`. Never quote a cache-hit rate from `tool_calls`: its `input_tokens` / `output_tokens` / `cached_tokens` columns exist in `src/db_schema.js` but nothing on the MCP path writes them.
40
+ | Need | Call |
41
+ |---|---|
42
+ | Canonical repository rules the runtime enforces | `get_skill("konoha/contract")` |
43
+ | Feedback/Task/Rules and Result/Evidence/Blockers/Next envelopes | `get_skill("konoha/task-format")` |
44
+ | MCP tool block every subagent must follow | `get_skill("konoha/mcp-tools-block")` |
45
+ | Per-agent tool permissions, worktrees, compact skill loading | `get_skill("konoha/peragent-usage")` |
74
46
 
75
- 28. **A Path Is Not Whitespace-Delimited**: any code that turns a string into a command must survive an executable path containing spaces, because that is the Windows default (`C:\Program Files\nodejs\node.exe`) rather than an edge case. `_parseCommandSpec` (`src/code_intel/lsp_manager.js`) accepted only a whitespace-split string and therefore resolved `C:\Program`, so every LSP leg reported `server binary missing` on Windows while passing on Linux and macOS. The rule: take an **array** as the unambiguous form (element 0 verbatim), honour `"…"`/`'…'` quoting in the string form, and report an unquoted spaced path as a missing binary instead of silently resolving a prefix — a wrong-but-plausible command is worse than a refusal. `src/platform_utils.js#normalizeCommand` already follows this shape; copy it rather than writing a new splitter.
76
- 29. **A Payload Gate Measures the Worst Client, and a Call Carried as Data Is Not Repeated in Prose**: `runSannin` output is capped by `tests/test_e2e_install_upgrade_reinstall.js`, and a cap that reads `detectActiveClient()` is not a gate — the same commit reported 2 951 bytes on one host and 3 315 on another, because OMP native `task(...)` is the longest spawn form of the ten. The loop now pins `server.ACTIVE_CLIENT` for each client, keeps the maximum, and names it in the failure. The other half is dedupe: `advisor_spawn_directive` exists to carry the advisor spawn call as a field, so interpolating the same string into `instructions` pays for it twice (~299 B per response on OMP). Point at the field instead. A field nothing reads is not "carried" — delete it: `buildAdvisorStartupDirective` built a markdown `directive` string no caller consumed, while `supported_native` is asserted per client by `tests/test_subagent_spawning_p0.js` and stays. Raising a cap is the last resort; if it moves, the new number is measured across every client and recorded in `docs/QA-TEST-CHECKLIST.md`.
47
+ Maintenance, architecture, invariants, benchmark evidence, and test inventory are maintainer-only: they live in the repository at `.agents/dev-skills/konoha-maintenance/` and are not shipped to client skill directories.
77
48
 
78
- ---
79
-
80
- ## 🚀 Quick Verification Commands
49
+ ## 🚀 Quick Commands
81
50
 
82
51
  ```bash
83
- # Verify version consistency across all 18 managed targets
84
- rtk node scripts/bump_version.js --check
85
- rtk node tests/test_version_consistency.js
86
-
87
- # Verify Draw.io zero geometric collisions
88
- rtk node tests/test_diagram_sync.js
89
-
90
- # Verify animated WebP assets
91
- rtk node tests/test_all_assets_webp.js
92
-
93
- # Verify LangGraph.js workflow activation (file keeps its historical v2217 name)
94
- rtk node tests/test_langgraph_v2217.js
95
-
96
- # Verify the runtime is free of dynamic execution and the emitted hooks still guard
97
- rtk node tests/test_no_dynamic_execution.js
98
-
99
- # Verify supply-chain posture (no lodash, patch intact, exact pins, frozen publish install)
100
- rtk node tests/test_dependency_posture.js
101
- rtk node tests/test_xlsx_populate_lodash_lite.js
102
- rtk node tests/test_document_engine_security.js
103
- rtk node tests/test_socket_security_audit.js
104
-
105
- # Verify cross-platform install, upgrade, schema, and runtime-mirror integrity
106
- rtk node tests/test_install_layout_integrity.js
107
- rtk node tests/test_install_lifecycle_and_db_preservation.js
108
- rtk node tests/test_install_migrate_embed_functions.js
109
- rtk node tests/test_pnpm_config_migration.js
110
- rtk node tests/test_upgrade_failure_reporting.js
111
- rtk node tests/test_upgrade_timeout_budgets.js
112
- rtk node tests/test_upgrade_version_verification.js
113
- rtk node tests/test_upgrade_cyber_pack_purge.js
114
- rtk node tests/test_config_backup_and_append_only.js
115
- rtk node tests/test_config_centralization.js
116
- rtk node tests/test_global_install.js
117
- rtk node tests/test_global_skill_sync_8_clients.js
118
- rtk node tests/test_schema_migrations_and_lifecycle.js
119
-
120
- # Verify MCP argument boundaries, skill URI resolution, and red-skill precedence
121
- rtk node tests/test_mcp_argument_parsing.js
122
- rtk node tests/test_skill_uri_resolution.js
123
- rtk node tests/test_skill_retrieval_precedence.js
124
-
125
- # Verify the first-run login fix end to end (Playwright; boots the web app)
126
- rtk pnpm run test:e2e
127
-
128
- # 3 local cross-platform CI test environments (Linux, Windows, macOS)
129
- rtk pnpm test:sandbox -- --shard=1/8
130
- rtk pnpm ci:act && rtk pnpm ci:act:shard
131
- # Windows (inside dockur/windows guest): docker\windows-vm\oem\run-ci.cmd -Shard 1/8
132
- # macOS (Apple silicon): KONOHA_SANDBOX_RUNTIME=container pnpm test:sandbox -- --shard=1/8
133
-
134
- # Static analysis & Zero-AI-Slop audit
135
- rtk node scripts/lint.js
136
- rtk npx aislop scan --changes
52
+ rtk konoha doctor # runtime, schema, and client health
53
+ rtk konoha version # installed version
54
+ rtk konoha migrate # reindex skills and docs into SQLite FTS5
55
+ rtk konoha ui start # local web UI
137
56
  ```
138
-
139
- ---
140
-
141
- ## 🛡️ Code-Intel, Guardrail & Subagent Contracts
142
-
143
- - **HF Cache Parity (`src/hf_cache_resolver.js`)**: `src/vector_pipeline.js` delegates HuggingFace Hub cache discovery and `KONOHA_SEMANTIC_SEARCH` availability checks to `src/hf_cache_resolver.js` (keeping both modules well under the 700-line limit).
144
- - **Project-Only Konoha MCP Guardrail (`src/project_konoha_mcp_guardrail.js`, `src/guardrail_hitl.js`, `src/guardrail_exceptions.js`, `scripts/konoha_project_mcp_guard.js`)**: Active exclusively inside the Konoha repository (`isKonohaRepository`); rejects unrouted native file/search/shell/legacy-IPC (`prompt.md`, `delegate.md`, `delegated.md`, `result.md`) calls across all 8 harnesses unless routed through Konoha MCP and Konoha maintenance skills. A denial is a **branchable decision, not a dead end**: `GUARDRAIL_REMEDIATION` maps every denial code to a concrete fix, `--hitl` renders the menu (`block and try another way` / `accept with risk` + ≥8-char justification) on the controlling terminal — `/dev/tty`, or `CONIN$`/`CONOUT$` on Windows — when stdin is a pipe, and an accepted risk is stored as a code+tool-scoped entry with a TTL capped at one hour. Hooks stay non-interactive and fail-closed; `KONOHA_GUARD_NO_TTY=1` can only force a block. The exception store (`.konoha/guardrail-exceptions.json`, `.konoha/guardrail-audit.jsonl`) is itself an attack surface: a write to it from any tool path is denied with a non-acceptable code, and some denials (secret write, destructive shell, retired IPC/MCP, store write) cannot be accepted at all. Guards: `tests/test_project_konoha_mcp_guardrail.js` tests 9-15, including a real pty leg through `tests/helpers/pty_driver.py`.
145
- - **16 Code-Intel Languages (`src/code_intel/capabilities.js`)**: Supports `javascript`, `typescript`, `python`, `go`, `rust`, `c`, `cpp`, `shell`, `sql`, `php`, `ruby`, `kotlin`, `swift`, `dart`, `elixir`, `zig` (Tree-sitter WASM + fallback + optional stdio LSP); `java`, `csharp`, and `lua` are explicitly excluded (`EXCLUDED_LANGUAGES`).
146
- - **Fail-Closed Subagent Spawning, Turn-0 Idle `@advisor`, 100k Quota LangGraph Compaction & Live TODO Sync (`src/mcp/lazy_subagent.js`, `src/context_compaction.js`, `src/mcp/langgraph/checkpointer.js`, `src/mcp/todo_walkthrough_sync.js`, `src/workflow/kage-reviewer/advisor_monitor.js`, `src/context_budget.js`)**: Routes the 8 spawnable specialists (`kage`, `jonin`, `anbu`, `chunin`, `tokubetsu-jonin`, `genin`, `akatsuki`, `yamanaka`) via harness-native descriptors + `konoha run-agent` child processes, keeps `@advisor` idle from turn 0 (`<= 8,192 tokens` / `32,768 bytes` interrupt budget) to steer drifted agents, captures per-agent LangGraph SQLite checkpoints (`lg_checkpoints`, namespace `agent:<name>`) + compacts + auto-continues when reaching `agent_input_token_quota` (`100,000` default / `KONOHA_AGENT_INPUT_TOKEN_QUOTA`), and synchronizes full `client_todo_directive` (`native_payload`), `walkthrough_steps`, `TODO.md`, and `sdlc_tasks` across all 8 harnesses.
147
- - **Harness Identity Is Read From the State Directory, Not the Variable Name (`src/mcp/client_detection.js`, `src/mcp/subagent_spawner.js`)**: OMP exports PI's environment verbatim (`PI_SESSION_FILE`, `PI_SESSION_ID`, `PI_CODING_AGENT_DIR`, `PI_GIT_GUARD`) and sets no `OMP_*` marker, so a name-based check reports every OMP session as `pi` and every fresh CLI process dies at `UNSUPPORTED_NATIVE_SPAWN`. Detection therefore inspects the path (`/.omp/` → `omp`, `/.pi/` → `pi`); `ACTIVE_CLIENT`/`KONOHA_CLIENT` still outrank inference. `--execute` resolves the *installed harness binary* rather than the harness's in-session subagent tool, so `--client cli --execute` launches instead of refusing; the `omp` invocation uses `-p --append-system-prompt` because oclif rejects `--agent` with exit 2, and the `task()` directive it tells the model to call carries `solutionSpace` and no `cwd`, because OMP's schema is `{context, tasks:[{name?, agent, task, solutionSpace, …}]}` with `"+": "delete"`. On Windows the resolved `.cmd`/`.bat` shim is launched through `ComSpec /d /s /c` (Node refuses to spawn a shim directly) with the task's newlines flattened to spaces, since cmd.exe treats a newline as a command separator. Guarded by `tests/test_spawn_harness_contracts.js`.
148
- - **Provenance-Aware Native Knowledge Brain & Host Headed Browser QA (`src/memory_brain*.js`, `src/workflow/qa-automation/qa_tools.js`)**: Schema v9 (`45` raw / `33` declared tables; v9 is a data-repair bump, not a table bump — `setupSchema` folds legacy `agy` rows into `antigravity` via `src/db_schema_repairs.js`) stores durable knowledge across `persona`/`project`/`episodic`/`session`/`knowledge` domains with provenance, corrections, supersession, withdrawal, append-only `memory_audit_events`, deterministic `memory_relations`, and conservative dry-run/apply/revert maintenance. Interactive live headed Chromium runs on the host's own Playwright: `qa_e2e_run({ headed: true })` adds `--headed` and `KONOHA_PW_HEADED=1`, which the target config turns into `headless: false`, while `CI=1` drops both so CI stays headless.
149
- - **First-Use Code-Intel Indexing, Async Yield & the Row-Less `@advisor` Charter (`src/code_intel/auto_index.js`, `src/code_intel/search_setup.js`, `src/mcp/memory_subagent_runner.js`, `src/mcp/workflow_sannin.js`)**: `code_search`, `code_symbol`, `code_context`, `code_impact`, and `code_related` index a directory named for the first time instead of answering `root not indexed` — `ensureRootIndexed` runs a lexical-only pass (`embed: false`, `maxFiles: 5000`, `timeoutMs: 15000`), and `code_index` adds vectors later. The async handlers never take that blocking pass: `prepareSearchSetupAsync` and `_resolveAnchorAsync` await `indexRepositoryAsync`, so `tools/list` stays answerable. `code_status` keeps `store.getRoot` and stays read-only — indexing there would resurrect a root `code_remove` just cleared. A row is not proof of an index: `ensureRoot` inserts `stale` with `indexed_at NULL` before the walk, so `isUsableRoot` requires `fresh` or a completed `stale` and retries the rest; a partial completed pass returns `index_incomplete: true`. `@genin`/`@advisor` never trigger that write (`KONOHA_READONLY=1` or the detected agent), concurrent first-use queries share one in-flight pass, and the advisor CLI fallback carries `--execute` so it starts a process instead of printing a directive. `advisor` has no `agents` row by design (the table is the 9-ninja roster), so `_resolveAgentDbMetadata` falls back to `ADVISOR_AGENT_DEFINITION` at the read site rather than seeding it, and `sannin` emits the resolved `spawn_call` / CLI fallback instead of a bare `--idle` directive.
150
-
151
- ## 📜 Change History That Constrains Maintenance (v2.2.17 → v2.2.23)
152
-
153
- Read this before "fixing" the install, migrate, or upgrade path. Each row already shipped as a bug once.
154
-
155
- | Trap | Do not | Guard |
156
- |---|---|---|
157
- | Schema/version conflation | Derive `user_version` from the app version | `src/db_schema.js` is the only writer; `konoha doctor` prints `schema 9, app 2.2.23` |
158
- | Shelling out to migration | `spawnSync(process.execPath, [...migrate.js...])` and trust `status === 0` | in-process `runMigration()`, `tests/test_install_migrate_embed_functions.js` |
159
- | Silent budget truncation | Cap the embedding pass below the caller's timeout | `migrate_time_budget_seconds` 900 / `install_build_migrate_timeout_ms` 900000 |
160
- | `konoha embed` as a recovery hint | Recommend it for partial coverage | it implies `--rebuild-embeddings` → `DELETE FROM skill_chunks` then re-embeds everything (`src/vector_search.js:515`). Recovery is `konoha migrate` |
161
- | Shorter cyber-pack dir list | Hardcode client skill dirs | deduped union of `DEFAULT_SKILLS_DIRS` + `getGlobalHarnessSkillTargets()` |
162
- | Flat runtime mirror | `require('../bin/lib/...')` from a `src/` module | `src/config_access.js` |
163
- | Transitive `image-size` | Trust the lockfile | `overrides.image-size >= 2.0.3`, `bundleDependencies`, `pnpm pack` (npm `pack` / global install drop bundled deps) |
164
- | Patched dependency, unpatched consumer | Assume `pnpm-workspace.yaml#patchedDependencies` reaches users | `cfb` + `xlsx-populate` are both in `bundleDependencies`; `tests/test_global_install.js` asserts the patched copy ships and is the one resolved |
165
- | Install-script shim | Add `postinstall` back | no install scripts; `tests/test_global_install.js` |
166
- | PATH-blind upgrade report | Compare the package root with itself | `bin/lib/upgrade_verify.js` |
167
- | Doc-level pins | Let docs drift from code | `PROMPT_CEILING_BYTES` (`src/mcp/memory_subagent_runner.js`), asserted independently by `tests/test_remediation_contract.js` |
168
- | Over-claiming the token ceiling | Quote 8192 as the harness budget | `token_guard.js` bounds Konoha's internal LangGraph payload only |
169
- | Cyber-pack residue survives upgrade | Ship an upgrade that leaves legacy rows/on-disk copies and only `doctor --clean-cyber-pack` can remove them | `purgeLegacyResidue` runs from `src/migrate.js`; explicit opt-in is never destroyed; `tests/test_upgrade_cyber_pack_purge.js` |
170
- | Stdin EOF as the only MCP exit | Rely on `readline` `close` to end a stdio server | `startStdioOrphanGuard` (`ppid === 1` poll) + `mcp_stdio_idle_timeout_ms`; `tests/test_mcp_orphan_guard.js` |
171
- | "Already started" treated as current | Report success when a UI listener already holds the port | `konoha ui start` exits 1 with `already running`; `tests/test_ui_manual_only.js` |
172
- | Custom model cache or downloader | Reintroduce a bespoke Konoha model cache directory or downloader | `@huggingface/transformers` owns model loading and native `FileCache` (`HF_HOME`); `tests/test_bundled_models.test.js` |
173
- | Full `setupSchema` in hot paths | Call `db.setupSchema(conn)` inside repeated API handlers/loops | Use `db.ensureSchema(conn)` for runtime fast-path; keep `db.setupSchema(conn)` for full migration/cleanup tests |
174
- | `new Function` in an emitted payload | Compile a guardrail checker with `new Function(source)()` | embed it verbatim as a function expression; `tests/test_no_dynamic_execution.js` |
175
- | Caret on a patched or bundled dep | Let `^1.21.0` resolve to bytes the lockfile never saw | exact pins + `--frozen-lockfile` in `publish.yml`; `tests/test_dependency_posture.js` |
176
- | Regenerating the `xlsx-populate` patch from stock | Recreate it without `lib/lodash-lite.js` and the `browser/` deletion | `lodash` returns and the eval sink ships again; `tests/test_xlsx_populate_lodash_lite.js` |
177
- | Shipping a browser build | Let `jszip/dist/` or a `pptxgen.bundle.js` ride along in the tarball | they polyfill `setImmediate` with `new Function`; patch them out and assert the packed tree, `tests/test_dependency_posture.js` |
178
- | Editing a patch without reinstalling | Leave a stale `node_modules` that still holds the deleted bundle | `pnpm install` after every patch edit; `tests/test_dependency_posture.js` asserts the installed trees, not just the patch files |
179
- | `addImage({ path })` | Pass a filesystem path or URL into pptxgenjs | `addInlineImage(slide, buffer)` (PNG magic-byte checked) is the only call site |
180
- | Suppressing a Socket alert as a "fix" | Add `usesEval: false` or ignore `pnpm-lock.yaml` / `patches/**` | remove the sink instead; suppressions describe intent, `tests/test_socket_security_audit.js` |
181
- | Splicing only the first contract block | Replace the first `KONOHA-CONTRACT-START`…`END` pair and assume the file is clean | `buildManagedContract` strips **every** span first; a second block made redeploy a no-op and shipped 2.2.23 beside 2.2.12, `tests/test_omp_manager.js` |
182
- | Procedure in the per-turn addendum | Put framework scaffolding commands or scan procedure in `buildOmpWorkflowAddendum` | those load on demand from `jonin-skill` / `konoha` references; the addendum is paid every request, `tests/test_lightweight_contracts.js` (≤ 4200 B) |
183
- | Writing to `~/.omp/AGENTS.md` | Treat it as OMP's user context file | the native user path is `~/.omp/agent/AGENTS.md`; the dot-directory copy is never injected, so a contract deployed there is invisible |
184
- | Quoting a cache-hit rate from `tool_calls` | Read `cached_tokens` / `input_tokens` / `output_tokens` as if they were recorded | the columns exist but no MCP path writes them; measure payload bytes instead, `src/tools_savings_logger.js` |
185
- | Stripping the legacy roster block for "savings" | Delete `<!-- KONOHA-START -->` from `~/.omp/agent/AGENTS.md` | it is the **only** roster in that file (`buildMainAgentContract('omp')` carries none); deleting it is a behavior regression, not a saving |
186
- | Narrowing agent-file ownership to the frontmatter marker | Detect Konoha-owned agent files by `generated_by: konoha` alone | pre-marker releases identify themselves by the contract block; without it every deploy parks its own output as `.konoha-proposed` and `@genin` keeps `Write`/`Edit`/`Bash` forever (`src/agent_file_safety.js`, `tests/test_deploy_safety.js`) |
187
- | Auto-detecting a project from `cwd` under a temp `HOME` | Let `ensureOmpSetup` write `cwd/.omp/mcp.json` for any caller | a sandboxed run then points the checkout at a launcher that dies with it, and every delegated agent starts without `konoha.*`; compare against `os.userInfo().homedir`, never `process.env.HOME` (`src/omp_manager.js`, `tests/test_omp_manager.js`) |
188
- | Prompting from inside a hook | Make `PreToolUse` wait for a human answer | a hook gets one JSON reply and no controlling terminal; the interactive path is `--hitl` in `scripts/konoha_project_mcp_guard.js`, and it prompts on `/dev/tty` (the payload owns stdin) or exits `2`; `tests/test_project_konoha_mcp_guardrail.js` (tests 12, 14) |
189
- | A denial with no alternative | Return "blocked" without naming the Konoha route | `describeGuardrailRemediation(code)` covers all eleven codes; an unnamed denial just teaches the agent to retry; test 9 |
190
- | Matching a risk acceptance by target path | Scope `_exceptionCovers` on the extracted path | `_extractTargetPath` returns grep's `pattern` first, so path equality rejects the call the human approved; match code + tool only |
191
- | A risk acceptance that never expires | Persist an exception with no TTL | 30-minute default, pruned on read; `tests/test_project_konoha_mcp_guardrail.js` (test 11) |
192
- | Committing the exception store | Let `.konoha/guardrail-*.json*` reach a tag | an acceptance is machine-local; both paths are gitignored |
193
- | Auto-accepting on the menu default | Treat an empty answer or EOF as accept | `askHitlDecision` maps `''` and EOF to block; accepting needs a justification of 8+ characters |
194
- | A relative `require` in the shipped plugin copy | Resolve `src/guardrail_hitl` with `require('../src/guardrail_hitl')` from `.agents/plugins/konoha-mcp-guard/scripts/` | that directory has no `src/` sibling, and because `_runHitl` is `async` the throw becomes a rejected promise: exit `2` — the code a real block returns — with only `Cannot find module` on stderr, so no briefing and no menu. Resolve every `src/` module through `_resolveSrcModule`; `tests/test_project_konoha_mcp_guardrail.js` (test 6) |
195
- | A guardrail that can be talked out of a rule | Let any write tool or `rtk` shell command reach `.konoha/guardrail-exceptions.json` | the store *is* the bypass, so the gated agent writes its own permission and passes the call it was just denied. Both branches deny `GUARDRAIL_STATE_WRITE_DENIED` for the two store files, `NON_ACCEPTABLE_CODES` (secrets, shell violations, the store itself, retired IPC) refuses to be recorded or honoured, and a stored TTL is clamped to `MAX_EXCEPTION_TTL_MS` on write and on read; `tests/test_project_konoha_mcp_guardrail.js` (test 15) |
196
- | Measuring `get_skill` without checking the mirror it read | Quote a token figure for a skill some client mirror never refreshed | twelve mirrors serve twelve clients; `getSkillsScanDirs()` is the list and `tests/test_skill_tree_parity.js` now compares every one against `src/templates/skills` |
197
-
198
- Only `skill`-type rows are exempt from the embedding time budget (`src/vector_search.js:533`). Reference documents can therefore remain unembedded after a "successful" migrate, and `runMigration` reports them via `deferredSkills`.
@@ -22,10 +22,10 @@ verifiable rules exist. No rule here is invented.
22
22
  3. `.omp/plans` must not be committed.
23
23
  4. Official Konoha skills must match the actual codebase.
24
24
  5. Manual documentation, diagrams, and asset review is mandatory.
25
- 6. Cross-platform compatibility across all 3 local CI test environments must be verified: (1) Linux (`pnpm test:sandbox [-- --shard=I/8]` Debian + `pnpm ci:act` / `pnpm ci:act:shard` Ubuntu `act`), (2) Windows (`docker/windows-vm/oem/run-ci.cmd [-Shard I/N]` / `retest.cmd` via `dockur/windows`), and (3) macOS (`KONOHA_SANDBOX_RUNTIME=container pnpm test:sandbox [-- --shard=I/8]` + `macos-latest` CI).
25
+ 6. Cross-platform compatibility across the 3 local CI legs must be verified as far as the host allows: (1) Linux (`pnpm test:sandbox [-- --shard=I/N]` Debian + `pnpm ci:act` / `pnpm ci:act:shard` Ubuntu `act`), (2) Windows (`docker/windows-vm/oem/run-ci.cmd [-Shard I/N]` / `retest.cmd` via `dockur/windows`), and (3) macOS — either a native/`macos-latest` run, Apple `container`, or a `dockur/macos` guest, or, on a host that cannot provide a macOS kernel, the documented symlinked-`HOME` proxy from `docs/CI.md`. Run `node scripts/sandbox_preflight.js` to see which legs this host can actually provide. A leg the host cannot provide must be reported as `proxy-verified` or `blocked` with its reason — never as a native pass. Only a GitHub `macos-latest` run at 4 GB or more closes the macOS leg natively.
26
26
  7. Aislop gate: shipped code must pass `rtk npx aislop scan --changes` with score 100/100 Healthy, 0 errors, 0 warnings.
27
27
  8. Maximum 700 lines per file/script (`.js`, `.py`, `.svelte`; enforced by `scripts/lint.js`).
28
- 9. Local Socket CLI checks are mandatory after dependency changes.
28
+ 9. The local dependency audit is mandatory after dependency changes: `rtk node tests/test_dependency_audit.js` (`pnpm audit --json` over the root and `apps/web` workspaces, no account or token). The Socket.dev scan is opt-in only (`pnpm audit:socket` with `SOCKET_CLI_API_TOKEN`) and never blocks CI.
29
29
  10. SecurityCompliance must match actual implementation.
30
30
  11. Local commit author: `andycungkrinx91 <andy.silva270114@gmail.com>`.
31
31
  12. Konoha is mandatory: use bounded file tools and Konoha skill lookup (`find_skill`, `get_skill`); no raw `cat`/`grep`.
@@ -1,4 +1,4 @@
1
- # 🍃 Konoha 9-Ninja Specialist Roster, Parallel Worktree Isolation & Operational Boundaries (v2.2.23)
1
+ # 🍃 Konoha 9-Ninja Specialist Roster, Parallel Worktree Isolation & Operational Boundaries (v2.2.25)
2
2
 
3
3
  Technical reference on the 9-agent roster (`@sannin` router + 8 spawnable specialists), parallel git worktree contracts, strict tool permission matrices, compact skill loading (`use_skills`), and ADHD/anti-slop discipline.
4
4
 
@@ -0,0 +1,57 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * src/token_usage.js — provider-reported token usage, recorded or explicitly absent.
5
+ *
6
+ * The budget report and the savings logger both used to present byte-derived
7
+ * estimates as if a provider had measured them. Keeping the two apart is the
8
+ * point of this module: `normalizeUsage` returns `available: false` with a
9
+ * reason when a provider said nothing, so no caller can print a fabricated
10
+ * number where a measurement belongs.
11
+ */
12
+
13
+ const { extractCachedTokens } = require('./bridge/cache_capability');
14
+
15
+ /** Provider field spellings that carry a real prompt/completion count. */
16
+ const INPUT_KEYS = ['prompt_tokens', 'input_tokens', 'promptTokenCount'];
17
+ const OUTPUT_KEYS = ['completion_tokens', 'output_tokens', 'candidatesTokenCount'];
18
+
19
+ function _firstFinite(source, keys) {
20
+ for (const key of keys) {
21
+ const value = source[key];
22
+ if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return value;
23
+ }
24
+ return null;
25
+ }
26
+
27
+ /**
28
+ * Normalize a provider usage object onto the fields every consumer reads.
29
+ *
30
+ * @param {object|null} usage raw provider usage
31
+ * @returns {{available: boolean, reason?: string, input_tokens: number|null,
32
+ * output_tokens: number|null, total_tokens: number|null, cache_read_input_tokens: number|null}}
33
+ * `available` is false whenever no provider count was present. The token
34
+ * fields are then null, never 0: "not measured" is not "measured zero".
35
+ */
36
+ function normalizeUsage(usage) {
37
+ const absent = { available: false, reason: 'no provider usage recorded', input_tokens: null, output_tokens: null, total_tokens: null, cache_read_input_tokens: null };
38
+ if (!usage || typeof usage !== 'object') return absent;
39
+
40
+ const input = _firstFinite(usage, INPUT_KEYS);
41
+ const output = _firstFinite(usage, OUTPUT_KEYS);
42
+ const total = _firstFinite(usage, ['total_tokens', 'totalTokenCount'])
43
+ ?? (input !== null && output !== null ? input + output : null);
44
+ const cached = extractCachedTokens(usage);
45
+
46
+ if (input === null && output === null) return absent;
47
+ return {
48
+ available: true,
49
+ method: 'provider_reported',
50
+ input_tokens: input,
51
+ output_tokens: output,
52
+ total_tokens: total,
53
+ cache_read_input_tokens: cached
54
+ };
55
+ }
56
+
57
+ module.exports = { normalizeUsage };
@@ -179,10 +179,19 @@ function _resolveCorpusBaseline(conn, tool, query, returnedBytes) {
179
179
  }
180
180
  }
181
181
 
182
- function log(tool, query, returnedBytes, client = null, _baselineBytes = null) {
183
- if (!client) {
184
- client = detectActiveClient();
185
- }
182
+ /**
183
+ * Log a tool call.
184
+ * @param {string} tool
185
+ * @param {string} query
186
+ * @param {number} returnedBytes
187
+ * @param {string|{client?:string|null, usage?:object|null}|null} [opts]
188
+ * A client id (legacy positional form) or `{ client, usage }`. `usage`
189
+ * is only ever a provider payload; it is never derived from bytes.
190
+ */
191
+ function log(tool, query, returnedBytes, opts = null) {
192
+ const fromOptions = opts && typeof opts === 'object' && !Array.isArray(opts);
193
+ const client = (fromOptions ? opts.client : opts) || detectActiveClient();
194
+ const usage = fromOptions ? (opts.usage ?? null) : null;
186
195
  const conn = getDb();
187
196
  try {
188
197
  const baseline = _calculateBaseline(conn, tool, query, returnedBytes);
@@ -190,10 +199,15 @@ function log(tool, query, returnedBytes, client = null, _baselineBytes = null) {
190
199
  const bytesSaved = Math.max(baseline - retBytes, 0);
191
200
  const tokensSaved = Math.floor(bytesSaved / 4);
192
201
 
193
- conn.prepare(`
202
+ // Usage columns are written only from a provider payload. Absent that they
203
+ // stay NULL: `input_tokens IS NULL` is how a reader tells an unreported
204
+ // count from a measured zero.
205
+ const measured = require('./token_usage').normalizeUsage(usage);
206
+ const info = conn.prepare(`
194
207
  INSERT INTO tool_calls
195
- (tool, query, returned_bytes, total_library_bytes, bytes_saved, tokens_saved, client)
196
- VALUES (?, ?, ?, ?, ?, ?, ?)
208
+ (tool, query, returned_bytes, total_library_bytes, bytes_saved, tokens_saved, client,
209
+ input_tokens, output_tokens, cached_tokens)
210
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
197
211
  `).run(
198
212
  String(tool || '').slice(0, 200),
199
213
  String(query || '').slice(0, 2000),
@@ -201,8 +215,12 @@ function log(tool, query, returnedBytes, client = null, _baselineBytes = null) {
201
215
  baseline,
202
216
  bytesSaved,
203
217
  tokensSaved,
204
- String(client || 'unattributed').slice(0, 100)
218
+ String(client || 'unattributed').slice(0, 100),
219
+ measured.available ? measured.input_tokens : null,
220
+ measured.available ? measured.output_tokens : null,
221
+ measured.available ? measured.cache_read_input_tokens : null
205
222
  );
223
+ return info;
206
224
  } catch (_) {
207
225
  // Fail-open: telemetry logging must never crash the tool runtime
208
226
  }
@@ -0,0 +1,58 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * src/url_canonical.js — URL canonicalization shared by web search and the
5
+ * Chunin knowledge store.
6
+ *
7
+ * Kept in its own module so `web_search.js` can dedupe without pulling in the
8
+ * database or the embedding pipeline.
9
+ */
10
+
11
+ // Tracking parameters that never change which page is served.
12
+ const TRACKING_PARAM_RE = /^(utm_[a-z_]+|fbclid|gclid|mc_cid|mc_eid|ref|ref_src|source|igshid|yclid|_ga)$/i;
13
+
14
+ /**
15
+ * Canonicalizes a URL for dedupe: forces https, lowercases the host, drops
16
+ * tracking parameters, sorts the rest, and removes a trailing slash, an
17
+ * index page or a fragment. Two spellings of the same page collapse to one key.
18
+ *
19
+ * @param {string} rawUrl
20
+ * @returns {string} canonical form, or '' when the input is not an http(s) URL
21
+ */
22
+ function canonicalizeUrl(rawUrl) {
23
+ if (!rawUrl || typeof rawUrl !== 'string') return '';
24
+ let parsed;
25
+ try {
26
+ parsed = new URL(rawUrl.trim());
27
+ } catch (_) {
28
+ return '';
29
+ }
30
+ if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return '';
31
+
32
+ parsed.protocol = 'https:';
33
+ parsed.hostname = parsed.hostname.toLowerCase();
34
+ parsed.hash = '';
35
+
36
+ const keep = [];
37
+ for (const [key, value] of parsed.searchParams.entries()) {
38
+ if (TRACKING_PARAM_RE.test(key)) continue;
39
+ keep.push([key, value]);
40
+ }
41
+ keep.sort((a, b) => (a[0] === b[0] ? a[1].localeCompare(b[1]) : a[0].localeCompare(b[0])));
42
+ parsed.search = '';
43
+ for (const [key, value] of keep) parsed.searchParams.append(key, value);
44
+
45
+ let out = parsed.toString();
46
+ // 'https://a.com' renders as 'https://a.com/'. Strip a trailing slash from a
47
+ // non-root path whether or not a query is present, so '/a/?b=2' and '/a?b=2'
48
+ // are the same page.
49
+ if (parsed.pathname && parsed.pathname !== '/' && parsed.pathname.endsWith('/')) {
50
+ parsed.pathname = parsed.pathname.replace(/\/+$/, '');
51
+ out = parsed.toString();
52
+ }
53
+ if (parsed.pathname === '/' && !parsed.search) out = out.replace(/\/$/, '');
54
+ out = out.replace(/\/index\.html?$/i, '');
55
+ return out;
56
+ }
57
+
58
+ module.exports = { canonicalizeUrl, TRACKING_PARAM_RE };
@@ -17,10 +17,12 @@ const SEMANTIC_SEARCH_ENV = 'KONOHA_SEMANTIC_SEARCH';
17
17
  const EMBED_MODEL_REPO = 'onnx-community/granite-embedding-97m-multilingual-r2-ONNX';
18
18
  const RERANK_MODEL_REPO = 'Xenova/ms-marco-MiniLM-L-6-v2';
19
19
  const EMBED_DIM = 384;
20
- // One sequence per ONNX call is 1.58x faster than 16 on the bundled granite-97m
21
- // q8 graph (44 295 live chunks: 201.5 vs 127.6 chunks/s, 220 s vs 347 s). Padding
22
- // waste is already ~0 at these widths, so the win is the int8 kernel at M=1, not
23
- // saved tokens. Callers can still raise it via `batchSize`.
20
+ // One sequence per ONNX call wins once padding is real: on a heterogeneous mix
21
+ // (40..1600 char chunks, 48 texts, best of 3) batch 1 measured 817 ms against 866
22
+ // ms at 4 and 941 ms at 16, because padding to the longest sequence in each batch
23
+ // costs more than the dispatch it saves. A homogeneous corpus hides this (batch 4
24
+ // then looks ~1.5x faster), which is why the default stays at 1. Callers with
25
+ // near-uniform widths can still raise it via `batchSize`.
24
26
  const DEFAULT_EMBED_BATCH_SIZE = 1;
25
27
  const DEFAULT_RERANK_BATCH_SIZE = 16;
26
28
  const DEFAULT_EMBED_MAX_LENGTH = 512;