@kernel.chat/kbot 3.99.35 → 4.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 <p align="center">
   <strong>kbot</strong><br>
-  Open-source terminal AI agent. 787+ tools. 35 agents. 20 providers. Dreams, learns, watches your system, controls your phone. $0 local.
+  Open-source terminal AI agent. 100+ specialist skills. 35 specialist agents. 20 providers. Dreams, learns, watches your system, controls your phone. $0 local.
 </p>
 
 <p align="center">
@@ -31,10 +31,17 @@ Most terminal AI agents lock you into one provider, one model, one way of workin
 - **Runs fully offline** — Embedded llama.cpp, Ollama, LM Studio, or Jan. $0, fully private.
 - **Learns your patterns** — Bayesian skill ratings + pattern extraction. Gets faster over time.
 - **35 specialist agents** — auto-routes your request to the right expert (coder, researcher, writer, guardian, quant, and 30 more). Run any agent manually: `kbot --agent <id> "<prompt>"`. List them: `kbot agents`.
-- **787+ tools** — files, bash, git, GitHub, web search, deploy, database, game dev, VFX, research, science, finance, security, music production, iPhone control, and more.
+- **100+ specialist skills** — files, bash, git, GitHub, web search, deploy, database, game dev, VFX, research, science, finance, security, music production, iPhone control, and more.
+- **v4.0 evidence-based curation** — went from 670 skills to ~100. Every kept skill has telemetry, agent reference, or test coverage. Everything else moved to plugins.
 - **Programmatic SDK** — use kbot as a library in your own apps.
 - **MCP server built in** — plug kbot into Claude Code, Cursor, VS Code, Zed, or Neovim as a tool provider.
 
+## Benchmarks
+
+Methodology-explicit comparison vs other CLI agents → [BENCHMARKS.md](./BENCHMARKS.md). TL;DR: kbot beats Aider (4.4×) and OpenCode (5.7×) on cold start; loses to Claude Code, Codex, and jcode on raw boot but wins on cost-per-task (BYOK + Ollama fallback), vertical depth (Ableton/security/computer-use/channels), and offline availability (~70% of representative tasks).
+
+Using jcode? Wire kbot in as an MCP backend → [templates/jcode-integration.md](./templates/jcode-integration.md).
+
 ## Use with Claude Code / Cursor / Zed
 
 kbot is designed to compound with your existing AI editor, not replace it. One command wires everything up — MCP server config + a Claude Code skill that pre-authorizes the integration so safety filters don't refuse legitimate kbot calls.
@@ -165,8 +172,8 @@ Checks security, documentation, code quality, CI/CD, community health, and DevOp
 |---|---|---|---|---|---|
 | AI providers | 20 | 1 | 1 | 6 | 75+ |
 | Specialist agents | 35 | 0 | 0 | 0 | 0 |
-| Built-in tools | 787+ | ~20 | ~15 | ~10 | ~15 |
-| Science tools | 114 | 0 | 0 | 0 | 0 |
+| Built-in skills | 100+ | ~20 | ~15 | ~10 | ~15 |
+| Science skills | included | 0 | 0 | 0 | 0 |
 | Memory system | 7-tier bidirectional | File-based | No | No | No |
 | Dream engine | Yes ($0 local) | Cloud API | No | No | No |
 | Service watchdog | Yes | No | No | No | No |
@@ -228,7 +235,9 @@ kbot auto-routes to the right agent for each task. Or pick one with `--agent <na
 | **Domain** | infrastructure, quant, investigator, oracle, chronist, sage, communicator, adapter |
 | **Presets** | claude-code, cursor, copilot, creative, developer |
 
-## 686+ Tools
+## 100+ Specialist Skills
+
+As of v4.0, kbot ships ~100 curated skills (down from 670 — every kept skill has telemetry, agent reference, or test coverage). The rest are available as plugins.
 
 | Category | Examples |
 |----------|---------|
@@ -320,7 +329,7 @@ graph TD
     D -->|Multi-step| F[Autonomous Planner]
     E --> G[Provider API + Tool Loop]
     F --> G
-    G --> H{686+ Tools}
+    G --> H{100+ Skills}
     H --> I[File ops, bash, git, GitHub, search, deploy, DB, game dev...]
     G --> J[Learning Engine]
     J --> K[Patterns + Solutions + User Profile]

package/dist/agent-protocol.js

@@ -391,6 +391,7 @@ export function getTrustReport() {
 export function registerAgentProtocolTools() {
     registerTool({
         name: 'agent_handoff',
+        deprecated: true,
         description: 'Create a handoff to transfer work to another agent. Includes context, artifacts, and priority. The receiving agent can accept or reject. Use this when a task is better suited for a different specialist.',
         parameters: {
             from: { type: 'string', description: 'Agent ID initiating the handoff', required: true },
@@ -430,6 +431,7 @@ export function registerAgentProtocolTools() {
     });
     registerTool({
         name: 'blackboard_write',
+        deprecated: true,
         description: 'Write to the shared agent blackboard (working memory). Any agent can write facts, hypotheses, decisions, artifacts, or questions. Other agents can read these to coordinate without direct communication.',
         parameters: {
             key: { type: 'string', description: 'Key to write (e.g., "architecture_decision", "security_finding")', required: true },
@@ -464,6 +466,7 @@ export function registerAgentProtocolTools() {
     });
     registerTool({
         name: 'blackboard_read',
+        deprecated: true,
         description: 'Read from the shared agent blackboard. Query a specific key or list all entries filtered by type. Use this to see what other agents have written and coordinate work.',
         parameters: {
             key: { type: 'string', description: 'Specific key to read. If omitted, returns all entries.' },
@@ -504,6 +507,7 @@ export function registerAgentProtocolTools() {
     });
     registerTool({
         name: 'agent_propose',
+        deprecated: true,
         description: 'Propose an approach for multi-agent negotiation. Other agents can vote agree/disagree/abstain. Use resolve to determine the outcome. Ties are broken by trust scores.',
         parameters: {
             action: { type: 'string', description: 'Action: propose, vote, resolve, or status', required: true },
@@ -589,6 +593,7 @@ export function registerAgentProtocolTools() {
     });
     registerTool({
         name: 'agent_trust',
+        deprecated: true,
         description: 'Check or update trust scores for agents. Trust is asymmetric: success adds 0.05, failure subtracts 0.10. Scores persist across sessions in ~/.kbot/trust.json.',
         parameters: {
             action: { type: 'string', description: 'Action: check, update, best, or report', required: true },

package/dist/cache-warmth.d.ts

@@ -0,0 +1,25 @@
+/** Anthropic prompt cache TTL — 5 minutes */
+export declare const CACHE_TTL_MS: number;
+/** Hash a system prompt to a short stable key */
+export declare function hashPrompt(text: string): string;
+/** Reset in-memory cache (test hook) */
+export declare function _resetCacheWarmthCache(): void;
+/** Record a successful API call's timestamp */
+export declare function recordCacheCall(model: string, promptHash: string, now?: number): void;
+export interface CacheWarmthCheck {
+    warm: boolean;
+    ageMs?: number;
+    estimatedExtraCostUSD?: number;
+    message?: string;
+}
+/**
+ * Check whether the prompt cache is still warm for (model, promptHash).
+ * Returns warm=true if no prior call OR within TTL. Returns warm=false
+ * with a chalk.yellow message when cold AND we haven't warned for this
+ * specific cold-event yet.
+ *
+ * @param costPerMTokInput USD per million input tokens (from auth.ts)
+ * @param promptTokenEstimate rough token count (e.g. text.length / 4)
+ */
+export declare function checkCacheWarmth(model: string, promptHash: string, costPerMTokInput: number, promptTokenEstimate: number, now?: number): CacheWarmthCheck;
+//# sourceMappingURL=cache-warmth.d.ts.map

package/dist/cache-warmth.js

@@ -0,0 +1,131 @@
+// kbot Cache Warmth — Anthropic prompt cache TTL warning
+//
+// Anthropic's prompt cache has a 5-minute TTL. If the next API call lands
+// after the cache expired, the user pays full input-token price instead
+// of the cached price. This module tracks per-(model, prompt-hash) call
+// timestamps and warns once per cold event.
+//
+// State persists at ~/.kbot/cache-warmth.json (atomic tmp+rename writes).
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import chalk from 'chalk';
+/** Anthropic prompt cache TTL — 5 minutes */
+export const CACHE_TTL_MS = 5 * 60 * 1000;
+/** State file location — overridable via KBOT_CACHE_WARMTH_PATH (test hook) */
+function statePath() {
+    return process.env.KBOT_CACHE_WARMTH_PATH || join(homedir(), '.kbot', 'cache-warmth.json');
+}
+/** Hash a system prompt to a short stable key */
+export function hashPrompt(text) {
+    return createHash('md5').update(text).digest('hex').slice(0, 16);
+}
+let cached;
+function emptyState() {
+    return { lastCall: {}, warnedColdEvents: {} };
+}
+function loadState() {
+    if (cached)
+        return cached;
+    try {
+        const path = statePath();
+        if (!existsSync(path)) {
+            cached = emptyState();
+            return cached;
+        }
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        cached = {
+            lastCall: parsed.lastCall || {},
+            warnedColdEvents: parsed.warnedColdEvents || {},
+        };
+        return cached;
+    }
+    catch {
+        cached = emptyState();
+        return cached;
+    }
+}
+function saveState(state) {
+    try {
+        const path = statePath();
+        const dir = dirname(path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const tmp = `${path}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(state), 'utf8');
+        renameSync(tmp, path);
+    }
+    catch {
+        // Non-fatal — state is best-effort
+    }
+}
+/** Reset in-memory cache (test hook) */
+export function _resetCacheWarmthCache() {
+    cached = undefined;
+}
+/** Build the composite key */
+function key(model, promptHash) {
+    return `${model}::${promptHash}`;
+}
+/** Record a successful API call's timestamp */
+export function recordCacheCall(model, promptHash, now = Date.now()) {
+    const state = loadState();
+    state.lastCall[key(model, promptHash)] = now;
+    saveState(state);
+}
+/** Format ms as "Nm Ss" */
+function formatAge(ms) {
+    const totalSec = Math.floor(ms / 1000);
+    const m = Math.floor(totalSec / 60);
+    const s = totalSec % 60;
+    return `${m}m ${s}s`;
+}
+/**
+ * Check whether the prompt cache is still warm for (model, promptHash).
+ * Returns warm=true if no prior call OR within TTL. Returns warm=false
+ * with a chalk.yellow message when cold AND we haven't warned for this
+ * specific cold-event yet.
+ *
+ * @param costPerMTokInput USD per million input tokens (from auth.ts)
+ * @param promptTokenEstimate rough token count (e.g. text.length / 4)
+ */
+export function checkCacheWarmth(model, promptHash, costPerMTokInput, promptTokenEstimate, now = Date.now()) {
+    if (process.env.KBOT_CACHE_WARMTH_WARN === 'off') {
+        return { warm: true };
+    }
+    const state = loadState();
+    const k = key(model, promptHash);
+    const last = state.lastCall[k];
+    // First call ever for this (model, prompt) — cache wasn't expected to exist
+    if (!last)
+        return { warm: true };
+    const ageMs = now - last;
+    if (ageMs <= CACHE_TTL_MS) {
+        return { warm: true, ageMs };
+    }
+    // Cold — but only warn once per cold-event (keyed on the prior lastCall ts)
+    const warned = state.warnedColdEvents[k] || [];
+    if (warned.includes(last)) {
+        return { warm: false, ageMs };
+    }
+    // Cost estimate: cached reads are ~10% of full input price; the cold
+    // call pays roughly 90% extra vs. the warm path it would have hit.
+    // We report the full input cost as the "extra" — a conservative upper
+    // bound that matches what the user actually pays for these tokens.
+    const extraUSD = (costPerMTokInput * promptTokenEstimate) / 1_000_000;
+    // Persist that we've warned so subsequent calls in the same cold-event
+    // (e.g. a tool loop) don't re-warn until a fresh warm window opens.
+    warned.push(last);
+    // Keep the list bounded
+    if (warned.length > 32)
+        warned.splice(0, warned.length - 32);
+    state.warnedColdEvents[k] = warned;
+    saveState(state);
+    const message = chalk.yellow(`[kbot] Anthropic prompt cache likely cold — last call was ${formatAge(ageMs)} ago (TTL is 5m). ` +
+        `This call will pay full input price (~$${extraUSD.toFixed(2)} more). ` +
+        `Run kbot doctor cache for tips.`);
+    return { warm: false, ageMs, estimatedExtraCostUSD: extraUSD, message };
+}
+//# sourceMappingURL=cache-warmth.js.map

package/dist/cli.js

@@ -102,7 +102,7 @@ async function main() {
         console.log(`  ${chalk.cyan('https://github.com/isaacsight/kernel/issues')}  ${chalk.dim('Bug reports')}`);
         console.log(`  ${chalk.cyan('support@kernel.chat')}  ${chalk.dim('Email (AI-assisted replies)')}`);
         console.log();
-        console.log(`  ${chalk.dim('35 specialist agents · 787+ tools · 20 providers · MIT licensed')}`);
+        console.log(`  ${chalk.dim('35 specialist agents · 100+ skills · 20 providers · MIT licensed')}`);
         console.log();
         process.exit(0);
     });
@@ -582,10 +582,10 @@ async function main() {
     // ── Discovery Agent ──
     const discoveryCmd = program
         .command('discovery')
-        .description('Autonomous outreach agent — finds conversations, drafts responses, posts for you');
+        .description('Background outreach agent — finds conversations, drafts responses, posts for you');
     discoveryCmd
         .command('start')
-        .description('Start the discovery loop — scans HN, GitHub, Reddit and posts autonomously')
+        .description('Start the discovery loop — scans HN, GitHub, Reddit and posts in the background')
         .option('--dry-run', 'Find and draft but don\'t post')
         .option('--interval <minutes>', 'Poll interval in minutes', '60')
         .option('--model <model>', 'Ollama model for analysis', 'qwen2.5-coder:32b')
@@ -4202,7 +4202,7 @@ async function main() {
             const models = await listOllamaModels();
             if (models.length > 0)
                 printInfo(`${models.length} models available. Using: ${ollamaModel || PROVIDERS.ollama.defaultModel}`);
-            printInfo('670+ tools ready. Type your prompt or press Enter for interactive mode.');
+            printInfo('100+ skills ready. Type your prompt or press Enter for interactive mode.');
         }
         else {
             printError(`Cannot reach Ollama at ${ollamaHost}. Is it running?`);
@@ -4696,7 +4696,7 @@ async function byokFlow() {
     console.log();
     printSuccess(`BYOK mode enabled — ${providerConfig.name}`);
     printInfo('You pay the provider directly. No message limits. No restrictions.');
-    printInfo('All 362 tools + 35 agents + learning system = yours.');
+    printInfo('All 100+ skills + 35 specialist agents + learning system = yours.');
     console.log();
     printSuccess('Ready. Run `kbot` to start.');
 }
@@ -4996,7 +4996,7 @@ async function startRepl(agentOpts, context, tier, byokActive = false, localActi
         const suggestions = await detectProjectSuggestions();
         console.log();
         console.log(chalk.dim('  ┌─────────────────────────────────────────────────┐'));
-        console.log(chalk.dim('  │') + chalk.bold('  35 agents. 362 tools. Just say what you need.  ') + chalk.dim(' │'));
+        console.log(chalk.dim('  │') + chalk.bold('  35 agents. 100+ skills. Just say what you need.  ') + chalk.dim(' │'));
         console.log(chalk.dim('  │                                                 │'));
         if (suggestions.length > 0) {
             for (const s of suggestions.slice(0, 4)) {

package/dist/plugin-sdk.d.ts

@@ -35,6 +35,17 @@ export interface PluginConfig {
     enabled: string[];
     disabled: string[];
 }
+export interface LoadPluginsOptions {
+    /** Override the plugin directory (used by tests). Defaults to ~/.kbot/plugins. */
+    pluginsDir?: string;
+    /** Override the integrity manifest path. Defaults to ~/.kbot/plugins.json. */
+    manifestPath?: string;
+    /**
+     * Override the integrity-disabled flag. Defaults to reading
+     * `process.env.KBOT_PLUGIN_INTEGRITY === 'off'`.
+     */
+    integrityDisabled?: boolean;
+}
 export interface SDKPluginManifest {
     name: string;
     version: string;
@@ -53,8 +64,18 @@ export interface SDKPluginManifest {
 /**
  * Load all installed and enabled SDK plugins.
  * Called at startup after the legacy plugins.ts loadPlugins() runs.
- */
-export declare function loadPlugins(verbose?: boolean): Promise<SDKPluginManifest[]>;
+ *
+ * Integrity contract (mirrors plugins.ts):
+ *   - Reads the same manifest at `~/.kbot/plugins.json` (override via
+ *     `KBOT_PLUGIN_MANIFEST` or `opts.manifestPath`).
+ *   - If the manifest exists, only plugins whose `name` appears in
+ *     `result.verified` are imported. Drift → throws `IntegrityError`.
+ *   - If the manifest is missing, falls back to back-compat behaviour: all
+ *     discovered, enabled plugins are imported (with a yellow info note).
+ *   - `KBOT_PLUGIN_INTEGRITY=off` skips verification entirely with a loud
+ *     yellow warning.
+ */
+export declare function loadPlugins(verbose?: boolean, opts?: LoadPluginsOptions): Promise<SDKPluginManifest[]>;
 /**
  * Scaffold a new plugin with a full project structure.
  * Creates ~/.kbot/plugins/<name>/ with index.ts and package.json.

package/dist/plugin-sdk.js

@@ -21,11 +21,32 @@ import { join, basename, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import { execSync } from 'node:child_process';
+import chalk from 'chalk';
 import { registerTool } from './tools/index.js';
+import { IntegrityError, verifyAllPlugins, enforce, } from './plugins-integrity.js';
 // ── Constants ────────────────────────────────────────────────────────────
 const KBOT_DIR = join(homedir(), '.kbot');
 const PLUGINS_DIR = join(KBOT_DIR, 'plugins');
+// NOTE: PLUGINS_CONFIG (per-plugin enable/disable list) shares the path
+// `~/.kbot/plugins.json` with the integrity manifest used by plugins.ts. This
+// is a pre-existing collision in the SDK loader — the enable/disable JSON has
+// shape `{ enabled, disabled }`, while the integrity manifest has shape
+// `{ schemaVersion, plugins }`. In practice users running with the integrity
+// manifest must override the SDK config path, or the integrity manifest path,
+// via `KBOT_PLUGIN_MANIFEST`. The fix is out of scope for the integrity
+// wiring; flagged here so we do not mask the collision in tests.
 const PLUGINS_CONFIG = join(KBOT_DIR, 'plugins.json');
+/**
+ * Default integrity manifest path. Mirrors plugins.ts so a single manifest
+ * covers both drop-in `.js` plugins (handled by plugins.ts) and SDK-style
+ * directory plugins (handled here). The integrity manifest's `path` field is
+ * resolved relative to `~/.kbot/plugins/`, so:
+ *   - `hello.js`            → simple drop-in plugin
+ *   - `my-tool/index.js`    → SDK-style packaged plugin
+ * are both expressible in one manifest. Override via `KBOT_PLUGIN_MANIFEST`
+ * or the `manifestPath` option to `loadPlugins`.
+ */
+const DEFAULT_MANIFEST_PATH = join(homedir(), '.kbot', 'plugins.json');
 // ── State ────────────────────────────────────────────────────────────────
 const loadedSDKPlugins = new Map();
 const registeredCommands = new Map();
@@ -219,19 +240,22 @@ function registerPluginHooks(plugin) {
 /**
  * Discover local plugins in ~/.kbot/plugins/<name>/ directories.
  * Each directory should contain an index.ts or index.js file.
+ *
+ * Pass `pluginsDir` to scan a custom location (used by tests). Defaults to
+ * the module-level `PLUGINS_DIR` (`~/.kbot/plugins`).
  */
-function discoverLocalPlugins() {
-    ensureDir(PLUGINS_DIR);
+function discoverLocalPlugins(pluginsDir = PLUGINS_DIR) {
+    ensureDir(pluginsDir);
     const results = [];
     let entries;
     try {
-        entries = readdirSync(PLUGINS_DIR);
+        entries = readdirSync(pluginsDir);
     }
     catch {
         return results;
     }
     for (const entry of entries) {
-        const dirPath = join(PLUGINS_DIR, entry);
+        const dirPath = join(pluginsDir, entry);
         try {
             const stat = statSync(dirPath);
             if (!stat.isDirectory())
@@ -328,16 +352,91 @@ function discoverNpmPlugins() {
     }
     return results;
 }
+// ── Integrity Gate ───────────────────────────────────────────────────────
+/**
+ * Run the integrity manifest gate before loading any SDK plugin module.
+ *
+ * Mirrors `plugins.ts`'s `runIntegrityGate` so the two loaders enforce the
+ * same fail-closed contract against the same manifest at `~/.kbot/plugins.json`.
+ *
+ * Behaviour:
+ *   - If KBOT_PLUGIN_INTEGRITY=off (or `integrityDisabled === true`):
+ *     emit a yellow warning and return `null` (verification skipped, all
+ *     discovered plugins are eligible to load).
+ *   - If the manifest file does not exist: emit a yellow info note and
+ *     return `null` (back-compat — manifest is optional today).
+ *   - If the manifest exists and verifies: return the `VerifyAllResult` so
+ *     the caller can restrict loads to `result.verified`.
+ *   - If the manifest exists and any plugin fails: throw `IntegrityError`
+ *     (loader refuses to import any SDK plugin this session).
+ */
+async function runIntegrityGate(manifestPath, pluginsDir, integrityDisabled) {
+    if (integrityDisabled) {
+        console.error(chalk.yellow(`  ⚠ KBOT_PLUGIN_INTEGRITY=off — skipping integrity check for SDK plugins (NOT FOR PRODUCTION). ` +
+            `Plugins under ${pluginsDir} will load without hash checking.`));
+        return null;
+    }
+    if (!existsSync(manifestPath)) {
+        console.error(chalk.yellow(`  ⚠ no plugin manifest at ${manifestPath} — plugin SDK loaded without integrity verification. ` +
+            `Create one to pin plugins by SHA-256 (see PLUGINS_INTEGRITY.md).`));
+        return null;
+    }
+    try {
+        const result = await verifyAllPlugins(manifestPath, pluginsDir);
+        if (result.failed.length > 0) {
+            const lines = result.failed
+                .map((f) => `    - ${f.name}: ${f.reason}`)
+                .join('\n');
+            console.error(chalk.red(`  ✗ Plugin integrity check failed for ${result.failed.length} SDK plugin(s):\n${lines}\n` +
+                `    Manifest: ${manifestPath}\n` +
+                `    To refresh hashes, recompute SHA-256 for each plugin entry and update the manifest. ` +
+                `Set KBOT_PLUGIN_INTEGRITY=off ONLY for local dev; never in production.`));
+            enforce(result); // throws IntegrityError
+        }
+        return result;
+    }
+    catch (err) {
+        if (err instanceof IntegrityError)
+            throw err;
+        // loadManifest threw (malformed JSON, schema violation, etc.) — fail closed.
+        console.error(chalk.red(`  ✗ Failed to load plugin integrity manifest at ${manifestPath}: ${err.message}`));
+        throw err;
+    }
+}
 // ── Public API ───────────────────────────────────────────────────────────
 /**
  * Load all installed and enabled SDK plugins.
  * Called at startup after the legacy plugins.ts loadPlugins() runs.
+ *
+ * Integrity contract (mirrors plugins.ts):
+ *   - Reads the same manifest at `~/.kbot/plugins.json` (override via
+ *     `KBOT_PLUGIN_MANIFEST` or `opts.manifestPath`).
+ *   - If the manifest exists, only plugins whose `name` appears in
+ *     `result.verified` are imported. Drift → throws `IntegrityError`.
+ *   - If the manifest is missing, falls back to back-compat behaviour: all
+ *     discovered, enabled plugins are imported (with a yellow info note).
+ *   - `KBOT_PLUGIN_INTEGRITY=off` skips verification entirely with a loud
+ *     yellow warning.
  */
-export async function loadPlugins(verbose = false) {
+export async function loadPlugins(verbose = false, opts = {}) {
+    const pluginsDir = opts.pluginsDir ?? PLUGINS_DIR;
+    const manifestPath = opts.manifestPath ?? process.env.KBOT_PLUGIN_MANIFEST ?? DEFAULT_MANIFEST_PATH;
+    const integrityDisabled = opts.integrityDisabled ?? process.env.KBOT_PLUGIN_INTEGRITY === 'off';
     const manifests = [];
-    // Discover from both sources
-    const localPlugins = discoverLocalPlugins();
-    const npmPlugins = discoverNpmPlugins();
+    // Integrity gate — runs BEFORE any SDK plugin file is imported. Throws
+    // IntegrityError on drift unless KBOT_PLUGIN_INTEGRITY=off.
+    const integrity = await runIntegrityGate(manifestPath, pluginsDir, integrityDisabled);
+    // When a manifest verified successfully, restrict loads to verified names.
+    // When the manifest is missing or integrity is disabled, allow every file.
+    const verifiedNames = integrity
+        ? new Set(integrity.verified)
+        : null;
+    // Discover from both sources. NPM plugins live in global node_modules and
+    // are not (yet) covered by the integrity manifest's relative-path scheme;
+    // when integrity is enforced, only local plugins listed in the manifest
+    // load. NPM plugins are skipped entirely under enforcement.
+    const localPlugins = discoverLocalPlugins(pluginsDir);
+    const npmPlugins = verifiedNames ? [] : discoverNpmPlugins();
     const allDiscovered = [
         ...localPlugins.map(p => ({ ...p, source: 'local' })),
         ...npmPlugins.map(p => ({ ...p, source: 'npm' })),
@@ -361,6 +460,17 @@ export async function loadPlugins(verbose = false) {
             manifests.push(manifest);
             continue;
         }
+        // When manifest verification ran, only load plugins whose name appears in
+        // the verified set. Discovered plugins not declared in the manifest are
+        // skipped (they could not have passed verification).
+        if (verifiedNames && !verifiedNames.has(name)) {
+            if (verbose) {
+                console.error(chalk.yellow(`  ⚠ [SDK] Skipping ${name} — not declared in plugin manifest`));
+            }
+            manifest.error = 'not declared in plugin integrity manifest';
+            manifests.push(manifest);
+            continue;
+        }
         try {
             const plugin = await importPlugin(entryPath);
             manifest.version = plugin.version;

package/dist/plugins.js

@@ -107,7 +107,21 @@ export async function loadPlugins(verbose = false, opts = {}) {
     const verifiedNames = integrity
         ? new Set(integrity.verified)
         : null;
-    const files = readdirSync(pluginsDir).filter(f => PLUGIN_EXTENSIONS.some(ext => f.endsWith(ext)));
+    // Top-level plugin files
+    const topLevel = readdirSync(pluginsDir).filter(f => PLUGIN_EXTENSIONS.some(ext => f.endsWith(ext)));
+    // Forged subdirectory (created by forge.ts at runtime). v3.99.31 and earlier
+    // persisted forged tools here without the loader scanning for them; fixed in v4.0.
+    let forgedFiles = [];
+    try {
+        const forgedDir = join(pluginsDir, 'forged');
+        forgedFiles = readdirSync(forgedDir)
+            .filter(f => PLUGIN_EXTENSIONS.some(ext => f.endsWith(ext)))
+            .map(f => `forged/${f}`);
+    }
+    catch {
+        // forged/ doesn't exist — nothing to load
+    }
+    const files = [...topLevel, ...forgedFiles];
     if (files.length === 0)
         return [];
     for (const file of files) {

package/dist/streaming.js

@@ -67,6 +67,24 @@ export async function streamAnthropicResponse(apiKey, apiUrl, model, system, mes
     }
     if (tools && tools.length > 0)
         body.tools = tools;
+    // Anthropic prompt-cache TTL warning (jcode borrow). Warn once per (model,
+    // prompt-hash) cold event when the cache likely expired since last call.
+    if (apiUrl.includes('anthropic') && system && process.env.KBOT_CACHE_WARMTH_WARN !== 'off') {
+        try {
+            const { hashPrompt, checkCacheWarmth, recordCacheCall } = await import('./cache-warmth.js');
+            const promptHash = hashPrompt(system);
+            const inputCostPerMTok = model.includes('opus') ? 15 : model.includes('haiku') ? 0.8 : 3;
+            const promptTokenEstimate = Math.ceil(system.length / 4);
+            const check = checkCacheWarmth(model, promptHash, inputCostPerMTok, promptTokenEstimate);
+            if (!check.warm && check.message) {
+                console.warn((await import('chalk')).default.yellow(check.message));
+            }
+            recordCacheCall(model, promptHash);
+        }
+        catch {
+            // never let warning logic break the API call
+        }
+    }
     let res;
     let lastError;
     for (let attempt = 0; attempt <= MAX_STREAM_RETRIES; attempt++) {

package/dist/tools/browser.js

@@ -50,6 +50,7 @@ export function registerBrowserTools() {
     });
     registerTool({
         name: 'browser_snapshot',
+        deprecated: true,
         description: 'Get the current page\'s accessibility tree (structured text representation).',
         parameters: {},
         tier: 'free',

package/dist/tools/computer.js

@@ -253,6 +253,7 @@ export function registerComputerTools() {
     // ── Permission & lock check ──
     registerTool({
         name: 'computer_check',
+        deprecated: true,
         description: 'Check computer use permissions and acquire the session lock. Call this before any other computer use tool. Returns permission status and any required setup steps.',
         parameters: {},
         tier: 'free',
@@ -277,6 +278,7 @@ export function registerComputerTools() {
     // ── App approval ──
     registerTool({
         name: 'app_approve',
+        deprecated: true,
         description: 'Approve an app for computer use in this session. Must be called before interacting with an app. Shows a warning for sensitive apps (terminals, Finder, System Settings).',
         parameters: {
             app: { type: 'string', description: 'App name (e.g., "Safari", "Finder", "Xcode")', required: true },
@@ -456,6 +458,7 @@ export function registerComputerTools() {
     // ── Mouse click ──
     registerTool({
         name: 'mouse_click',
+        deprecated: true,
         description: 'Click at specific screen coordinates.',
         parameters: {
             x: { type: 'number', description: 'X coordinate', required: true },
@@ -873,6 +876,7 @@ export function registerComputerTools() {
     });
     registerTool({
         name: 'window_resize',
+        deprecated: true,
         description: 'Resize a window of a specific app.',
         parameters: {
             app: { type: 'string', description: 'App name', required: true },
@@ -926,6 +930,7 @@ export function registerComputerTools() {
     });
     registerTool({
         name: 'window_move',
+        deprecated: true,
         description: 'Move a window to specific screen coordinates.',
         parameters: {
             app: { type: 'string', description: 'App name', required: true },
@@ -1080,6 +1085,7 @@ export function registerComputerTools() {
     // ── Release lock ──
     registerTool({
         name: 'computer_release',
+        deprecated: true,
         description: 'Release the computer use lock and end the session. Call when done with computer use.',
         parameters: {},
         tier: 'free',

package/dist/tools/containers.js

@@ -428,6 +428,7 @@ export function registerContainerTools() {
     // ── License Check ─────────────────────────────────────────────────
     registerTool({
         name: 'license_check',
+        deprecated: true,
         description: 'Check license compatibility across a project\'s dependency tree.',
         parameters: {
             path: { type: 'string', description: 'Project directory path', required: true },