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.
- package/NOTICE +14 -8
- package/README.md +20 -5
- package/apps/web/build/adapter-node.js +1 -1
- package/apps/web/build/build-meta.json +2 -2
- package/apps/web/build/client/_app/immutable/entry/{app.TYH87iYy.js → app.DtoBIrs4.js} +2 -2
- package/apps/web/build/client/_app/immutable/entry/app.DtoBIrs4.js.br +0 -0
- package/apps/web/build/client/_app/immutable/entry/app.DtoBIrs4.js.gz +0 -0
- package/apps/web/build/client/_app/immutable/nodes/{0.D7dPIEWA.js → 0.B8Iw7Xl1.js} +1 -1
- package/apps/web/build/client/_app/immutable/nodes/0.B8Iw7Xl1.js.br +0 -0
- package/apps/web/build/client/_app/immutable/nodes/{0.D7dPIEWA.js.gz → 0.B8Iw7Xl1.js.gz} +0 -0
- package/apps/web/build/client/_app/immutable/nodes/{13.TOXVaTBr.js → 13.CQB_Ed6W.js} +1 -1
- package/apps/web/build/client/_app/immutable/nodes/13.CQB_Ed6W.js.br +0 -0
- package/apps/web/build/client/_app/immutable/nodes/{13.TOXVaTBr.js.gz → 13.CQB_Ed6W.js.gz} +0 -0
- package/apps/web/build/client/_app/version.json +1 -1
- package/apps/web/build/client/_app/version.json.br +0 -0
- package/apps/web/build/client/_app/version.json.gz +0 -0
- package/apps/web/build/server/chunks/instance.js +3 -3
- package/apps/web/build/server/chunks/internal.js +1 -1
- package/apps/web/build/server/entries/pages/_layout.svelte.js +1 -1
- package/apps/web/build/server/entries/pages/_layout.svelte.js.map +1 -1
- package/apps/web/build/server/entries/pages/docs/_page.svelte.js +1 -1
- package/apps/web/build/server/entries/pages/docs/_page.svelte.js.map +1 -1
- package/apps/web/build/server/manifest-full.js +1 -1
- package/apps/web/build/server/manifest.js +1 -1
- package/apps/web/build/server/nodes/0.js +1 -1
- package/apps/web/build/server/nodes/13.js +1 -1
- package/apps/web/build/server/server.js +1 -1
- package/apps/web/package.json +1 -1
- package/assets/demo-agy.webp +0 -0
- package/assets/demo-claude.webp +0 -0
- package/assets/demo-codex.webp +0 -0
- package/assets/demo-commandcode.webp +0 -0
- package/assets/demo-cursor.webp +0 -0
- package/assets/demo-opencode.webp +0 -0
- package/assets/demo-pi.webp +0 -0
- package/assets/demo-skill-embed.webp +0 -0
- package/assets/demo-skills.webp +0 -0
- package/assets/demo-web.webp +0 -0
- package/assets/demo.webp +0 -0
- package/assets/konoha-akatsuki-flow.webp +0 -0
- package/assets/konoha-anbu-flow.webp +0 -0
- package/assets/konoha-flow-12-cli-upgrade-progress-engine.webp +0 -0
- package/assets/konoha-jonin-flow.webp +0 -0
- package/assets/konoha-kage-gate.webp +0 -0
- package/assets/konoha-langgraph-flow.webp +0 -0
- package/assets/konoha-orchestration-flow.webp +0 -0
- package/assets/konoha-qa-flow.webp +0 -0
- package/assets/konoha-telegram-flow.webp +0 -0
- package/assets/testing.webp +0 -0
- package/bin/commands/bridge.js +62 -4
- package/bin/commands/doctor.js +2 -0
- package/bin/commands/doctor_services.js +57 -0
- package/bin/commands/init.js +29 -8
- package/bin/commands/init_clients.js +95 -8
- package/bin/commands/init_migration.js +32 -1
- package/bin/lib/config_defaults.js +3 -0
- package/bin/lib/runtime_install.js +147 -54
- package/node_modules/jszip/package.json +2 -2
- package/node_modules/string_decoder/package.json +1 -1
- package/package.json +10 -3
- package/patches/gpt-tokenizer@4.1.0.patch +15 -0
- package/patches/jszip@3.10.2.patch +11 -0
- package/patches/string_decoder@1.3.0.patch +12 -0
- package/src/agent_contract.js +2 -2
- package/src/agent_deployer.js +48 -35
- package/src/agent_file_safety.js +57 -0
- package/src/antigravity_subagent_hook.js +30 -12
- package/src/bridge/gateway.js +2 -0
- package/src/bridge/gateway_adapters.js +155 -29
- package/src/bridge/handlers/anthropic.js +95 -26
- package/src/bridge/handlers/openai.js +18 -5
- package/src/bridge/sidecar/raw.js +10 -2
- package/src/bridge/stream_usage.js +66 -0
- package/src/chunin_knowledge_ddl.js +95 -0
- package/src/client_commands.js +190 -0
- package/src/db_bridges.js +53 -7
- package/src/db_schema.js +14 -2
- package/src/deploy_installer.js +212 -11
- package/src/deploy_utils.js +4 -0
- package/src/file_tools/common.js +65 -3
- package/src/file_tools_mcp.js +17 -9
- package/src/file_tools_router.js +67 -6
- package/src/global_skill_sync.js +3 -1
- package/src/mcp/chunin_knowledge.js +509 -0
- package/src/mcp/langgraph/edges/router.js +3 -0
- package/src/mcp/langgraph/index.js +22 -3
- package/src/mcp/langgraph/nodes/dispatch.js +3 -0
- package/src/mcp/langgraph/nodes/execute.js +87 -13
- package/src/mcp/langgraph/nodes/review.js +13 -1
- package/src/mcp/langgraph/slice_executor_registry.js +22 -0
- package/src/mcp/langgraph/state.js +5 -0
- package/src/mcp/lazy_subagent.js +11 -1
- package/src/mcp/memory_project_context.js +4 -1
- package/src/mcp/memory_subagent_runner.js +2 -1
- package/src/mcp/skills_common.js +1 -0
- package/src/mcp/subagent_spawner.js +7 -0
- package/src/mcp/todo_walkthrough_sync.js +7 -0
- package/src/mcp/tool_dispatch.js +18 -1
- package/src/mcp/web_search.js +27 -3
- package/src/mcp/workflow_completion_helpers.js +6 -1
- package/src/mcp/workflow_gates.js +118 -5
- package/src/mcp/workflow_sannin.js +9 -3
- package/src/mcp_clients/common.js +31 -0
- package/src/mcp_tool_manifest.json +36 -1
- package/src/pi_fs_helpers.js +31 -0
- package/src/pi_manager.js +68 -28
- package/src/provider_usage_logger.js +92 -0
- package/src/schema_ddl.js +17 -1
- package/src/templates/AGENTS.md +1 -1
- package/src/templates/GEMINI.md +1 -1
- package/src/templates/skills/chunin-skill/SKILL.md +34 -0
- package/src/templates/skills/chunin-skill/references/deep-research-analyst.md +27 -10
- package/src/templates/skills/kage-skill/SKILL.md +1 -1
- package/src/templates/skills/konoha/SKILL.md +23 -165
- package/src/templates/skills/konoha/references/contract.md +2 -2
- package/src/templates/skills/konoha/references/peragent-usage.md +1 -1
- package/src/token_usage.js +57 -0
- package/src/tools_savings_logger.js +26 -8
- package/src/url_canonical.js +58 -0
- package/src/vector_pipeline.js +6 -4
- package/src/vector_search.js +4 -2
- package/src/web/controllers/core_controller.js +10 -1
- package/src/workflow/jonin-builder/live_browser_monitor.js +23 -7
- package/apps/web/build/client/_app/immutable/entry/app.TYH87iYy.js.br +0 -0
- package/apps/web/build/client/_app/immutable/entry/app.TYH87iYy.js.gz +0 -0
- package/apps/web/build/client/_app/immutable/nodes/0.D7dPIEWA.js.br +0 -0
- package/apps/web/build/client/_app/immutable/nodes/13.TOXVaTBr.js.br +0 -0
- package/src/templates/skills/konoha/references/architecture.md +0 -99
- package/src/templates/skills/konoha/references/benchmark.md +0 -123
- package/src/templates/skills/konoha/references/docs.md +0 -46
- package/src/templates/skills/konoha/references/test.md +0 -71
- 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
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
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
|
-
```
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
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
|
-
- **
|
|
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:
|
|
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
|
|
13
|
+
# 🍃 Konoha MCP Tools Orchestrator Skill (v2.2.25)
|
|
15
14
|
|
|
16
|
-
|
|
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,
|
|
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
|
-
## 🔒
|
|
30
|
+
## 🔒 Working Rules
|
|
32
31
|
|
|
33
|
-
1. **Tool
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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
|
-
|
|
38
|
+
## 📚 Load On Demand
|
|
67
39
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
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
|
-
|
|
84
|
-
rtk
|
|
85
|
-
rtk
|
|
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
|
|
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.
|
|
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.
|
|
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
|
-
|
|
183
|
-
|
|
184
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 };
|
package/src/vector_pipeline.js
CHANGED
|
@@ -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
|
|
21
|
-
//
|
|
22
|
-
//
|
|
23
|
-
//
|
|
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;
|