konoha-mcp 2.2.23 → 2.2.24
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 +38 -0
- package/README.md +3 -3
- 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.CKJ0NhrX.js} +2 -2
- package/apps/web/build/client/_app/immutable/entry/app.CKJ0NhrX.js.br +0 -0
- package/apps/web/build/client/_app/immutable/entry/app.CKJ0NhrX.js.gz +0 -0
- package/apps/web/build/client/_app/immutable/nodes/{0.D7dPIEWA.js → 0.7A6fQJ6z.js} +1 -1
- package/apps/web/build/client/_app/immutable/nodes/0.7A6fQJ6z.js.br +0 -0
- package/apps/web/build/client/_app/immutable/nodes/{0.D7dPIEWA.js.gz → 0.7A6fQJ6z.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/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 +16 -5
- package/bin/commands/init_clients.js +95 -8
- package/bin/lib/config_defaults.js +3 -0
- package/bin/lib/runtime_install.js +141 -54
- package/package.json +2 -1
- package/patches/gpt-tokenizer@4.1.0.patch +15 -0
- package/src/agent_contract.js +1 -1
- package/src/agent_deployer.js +48 -35
- package/src/agent_file_safety.js +57 -0
- 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/client_commands.js +190 -0
- package/src/db_bridges.js +53 -7
- package/src/db_schema.js +11 -2
- package/src/file_tools_mcp.js +17 -9
- package/src/global_skill_sync.js +3 -1
- 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 +16 -0
- 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_tool_manifest.json +5 -1
- 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/kage-skill/SKILL.md +1 -1
- package/src/templates/skills/konoha/SKILL.md +23 -165
- package/src/templates/skills/konoha/references/contract.md +1 -1
- 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/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
|
@@ -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.24)
|
|
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`.
|
|
@@ -25,7 +25,7 @@ verifiable rules exist. No rule here is invented.
|
|
|
25
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).
|
|
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.24)
|
|
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
|
}
|
|
@@ -302,10 +302,18 @@ async function _handleSystemMetrics(req, res, sessionToken, systemMetrics) {
|
|
|
302
302
|
}
|
|
303
303
|
|
|
304
304
|
function _updateBridge(bridgeName, body) {
|
|
305
|
+
if (Object.prototype.hasOwnProperty.call(body, 'supports_stream_usage')) {
|
|
306
|
+
dbBridges.setStreamUsage(bridgeName, body.supports_stream_usage);
|
|
307
|
+
}
|
|
305
308
|
if (typeof body.enabled === 'boolean') {
|
|
306
309
|
dbBridges.setEnabled(bridgeName, body.enabled);
|
|
307
310
|
return null;
|
|
308
311
|
}
|
|
312
|
+
if (!body.port && !body.provider && !body.target_url) {
|
|
313
|
+
// Capability-only patch: forwarding it into upsertBridge would send NaN
|
|
314
|
+
// port/provider and replace the row with garbage.
|
|
315
|
+
return null;
|
|
316
|
+
}
|
|
309
317
|
if (body.target_url) {
|
|
310
318
|
const check = validateBridgeTargetUrl(body.target_url);
|
|
311
319
|
if (!check.ok) return check.reason;
|
|
@@ -343,7 +351,8 @@ async function _handleBridges(req, res, pathname, method, broadcastEvent) {
|
|
|
343
351
|
}
|
|
344
352
|
dbBridges.upsertBridge({
|
|
345
353
|
name: body.name, port: parseInt(body.port, 10), provider: body.provider,
|
|
346
|
-
enabled: body.enabled !== false, target_url: body.target_url || null, api_key: body.api_key || null
|
|
354
|
+
enabled: body.enabled !== false, target_url: body.target_url || null, api_key: body.api_key || null,
|
|
355
|
+
supports_stream_usage: body.supports_stream_usage
|
|
347
356
|
});
|
|
348
357
|
broadcastEvent('bridges_updated', { action: 'create', name: body.name });
|
|
349
358
|
return sendJson(res, 201, { ok: true, name: body.name });
|
|
@@ -84,7 +84,10 @@ function resolveSystemBrowserCommand(url, platform = process.platform) {
|
|
|
84
84
|
return { command: 'xdg-open', args: [safeUrl] };
|
|
85
85
|
}
|
|
86
86
|
|
|
87
|
-
|
|
87
|
+
// A detached spawn resolves asynchronously, so a missing opener (no `xdg-open` in a slim
|
|
88
|
+
// container) surfaces as an 'error' event on the ChildProcess, not as a throw: without a
|
|
89
|
+
// listener it kills the host process. Wait for 'spawn' or 'error', then report what happened.
|
|
90
|
+
async function openSystemBrowser(url, options = {}) {
|
|
88
91
|
const autoOpen = options.autoOpen !== false;
|
|
89
92
|
const isCi = Boolean(process.env.CI || process.env.KONOHA_HEADLESS_TEST === '1' || options.headless === true);
|
|
90
93
|
const spec = resolveSystemBrowserCommand(url, options.platform || process.platform);
|
|
@@ -96,25 +99,38 @@ function openSystemBrowser(url, options = {}) {
|
|
|
96
99
|
args: spec.args
|
|
97
100
|
};
|
|
98
101
|
}
|
|
102
|
+
let child;
|
|
99
103
|
try {
|
|
100
|
-
|
|
104
|
+
child = spawn(spec.command, spec.args, {
|
|
101
105
|
detached: true,
|
|
102
106
|
stdio: 'ignore'
|
|
103
107
|
});
|
|
104
|
-
|
|
108
|
+
} catch (err) {
|
|
105
109
|
return {
|
|
106
|
-
opened:
|
|
110
|
+
opened: false,
|
|
111
|
+
error: err.message,
|
|
107
112
|
command: spec.command,
|
|
108
113
|
args: spec.args
|
|
109
114
|
};
|
|
110
|
-
}
|
|
115
|
+
}
|
|
116
|
+
const failure = await new Promise((resolve) => {
|
|
117
|
+
child.once('spawn', () => resolve(null));
|
|
118
|
+
child.once('error', resolve);
|
|
119
|
+
});
|
|
120
|
+
if (failure) {
|
|
111
121
|
return {
|
|
112
122
|
opened: false,
|
|
113
|
-
error:
|
|
123
|
+
error: failure.message,
|
|
114
124
|
command: spec.command,
|
|
115
125
|
args: spec.args
|
|
116
126
|
};
|
|
117
127
|
}
|
|
128
|
+
child.unref();
|
|
129
|
+
return {
|
|
130
|
+
opened: true,
|
|
131
|
+
command: spec.command,
|
|
132
|
+
args: spec.args
|
|
133
|
+
};
|
|
118
134
|
}
|
|
119
135
|
|
|
120
136
|
function inspectMotionAnd3dCapabilities(html = '', sourceCode = '') {
|
|
@@ -338,7 +354,7 @@ async function runLiveBrowserMonitor(options = {}) {
|
|
|
338
354
|
: { ready: true, attempts: 0, status: 200, html: htmlOverride || '' };
|
|
339
355
|
|
|
340
356
|
const browserLaunch = serverState.ready
|
|
341
|
-
? openSystemBrowser(url, options)
|
|
357
|
+
? await openSystemBrowser(url, options)
|
|
342
358
|
: { opened: false, skipped_reason: 'server_not_ready' };
|
|
343
359
|
|
|
344
360
|
const inspection = serverState.ready
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|