@kernel.chat/kbot 4.0.0 → 4.1.0

package/dist/futures/persona/registry.js

@@ -0,0 +1,124 @@
+// futures/persona/registry — example personas. Hand-curated, not auto-generated.
+//
+// These three exist as concrete starting points for integration work; the
+// next session will wire them into permissions.ts. Until then they're
+// import-and-use values for tests and ad-hoc experimentation.
+/**
+ * Researcher: read-only research tools. Cannot mutate filesystem, repo, or
+ * external state. Web fetches and grep are fine; writes are not.
+ */
+export const RESEARCHER = {
+    id: 'researcher',
+    description: 'Read-only research and search tools. No filesystem writes, no shell execution.',
+    maxBlastRadius: 'read-only',
+    scopes: [
+        { toolPattern: 'read_file', blastRadius: 'read-only' },
+        { toolPattern: 'list_directory', blastRadius: 'read-only' },
+        { toolPattern: 'grep', blastRadius: 'read-only' },
+        { toolPattern: 'glob', blastRadius: 'read-only' },
+        { toolPattern: 'web_search', blastRadius: 'read-only' },
+        { toolPattern: 'papers_search', blastRadius: 'read-only' },
+        { toolPattern: 'kbot_search', blastRadius: 'read-only' },
+        { toolPattern: 'arxiv_search', blastRadius: 'read-only' },
+        { toolPattern: /^github_(read_file|repo_info|search|trending|activity|issues)$/, blastRadius: 'read-only' },
+    ],
+};
+/**
+ * Coder: read-write inside the workspace. Bash allowed but the most common
+ * destructive forms are denied via deny-pattern argRules. No force pushes.
+ * Rate limit on bash so a runaway loop can't burn 10k commands.
+ */
+export const CODER = {
+    id: 'coder',
+    description: 'Read-write code tools. Bash allowed but rm -rf and force-push denied. Bash 60/min.',
+    maxBlastRadius: 'sandboxed',
+    scopes: [
+        { toolPattern: 'read_file', blastRadius: 'read-only' },
+        { toolPattern: 'list_directory', blastRadius: 'read-only' },
+        { toolPattern: 'grep', blastRadius: 'read-only' },
+        { toolPattern: 'glob', blastRadius: 'read-only' },
+        { toolPattern: 'write_file', blastRadius: 'sandboxed' },
+        { toolPattern: 'edit_file', blastRadius: 'sandboxed' },
+        { toolPattern: 'multi_file_write', blastRadius: 'sandboxed' },
+        {
+            toolPattern: 'bash',
+            blastRadius: 'sandboxed',
+            argConstraints: {
+                // deny rm -rf at /, ~, or anywhere with force; deny sudo; deny curl|sh
+                command: {
+                    type: 'string',
+                    denyPattern: true,
+                    pattern: /(\brm\s+-[rRfF]+\s+(\/|~|\$HOME)|sudo\s+|curl\s+[^|]*\|\s*(sh|bash)|:\(\)\s*\{)/,
+                },
+            },
+            rateLimit: { max: 60, windowMs: 60_000 },
+        },
+        { toolPattern: /^git_(status|log|diff|branch|commit)$/, blastRadius: 'sandboxed' },
+        {
+            toolPattern: 'git_push',
+            blastRadius: 'sandboxed',
+            argConstraints: {
+                // forbid --force, --force-with-lease, -f
+                args: {
+                    type: 'string',
+                    denyPattern: true,
+                    pattern: /(^|\s)(--force(-with-lease)?|-f)(\s|$)/,
+                },
+            },
+        },
+        { toolPattern: /^npm_/, blastRadius: 'sandboxed' },
+        { toolPattern: /^pip_/, blastRadius: 'sandboxed' },
+    ],
+};
+/**
+ * Computer-use: explicit destructive opt-in. GUI tools that drive the user's
+ * physical desktop. Rate-limited so a hung loop can't spam clicks.
+ */
+export const COMPUTER_USE = {
+    id: 'computer-use',
+    description: 'Desktop control: mouse, keyboard, app launch. Destructive blast radius. 30/min.',
+    maxBlastRadius: 'destructive',
+    scopes: [
+        {
+            toolPattern: 'mouse_click',
+            blastRadius: 'destructive',
+            rateLimit: { max: 30, windowMs: 60_000 },
+        },
+        {
+            toolPattern: 'mouse_move',
+            blastRadius: 'destructive',
+            rateLimit: { max: 30, windowMs: 60_000 },
+        },
+        {
+            toolPattern: 'mouse_drag',
+            blastRadius: 'destructive',
+            rateLimit: { max: 30, windowMs: 60_000 },
+        },
+        {
+            toolPattern: 'keyboard_type',
+            blastRadius: 'destructive',
+            rateLimit: { max: 30, windowMs: 60_000 },
+        },
+        {
+            toolPattern: 'keyboard_shortcut',
+            blastRadius: 'destructive',
+            rateLimit: { max: 30, windowMs: 60_000 },
+        },
+        {
+            toolPattern: 'app_launch',
+            blastRadius: 'destructive',
+            rateLimit: { max: 30, windowMs: 60_000 },
+        },
+        { toolPattern: 'screenshot', blastRadius: 'read-only' },
+        { toolPattern: 'window_list', blastRadius: 'read-only' },
+    ],
+};
+/**
+ * Default registry. Add to this when wiring more personas.
+ */
+export const PERSONA_REGISTRY = {
+    researcher: RESEARCHER,
+    coder: CODER,
+    'computer-use': COMPUTER_USE,
+};
+//# sourceMappingURL=registry.js.map

package/dist/futures/persona/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Blast-radius hierarchy. Ordered from least to most dangerous.
+ * A Persona's maxBlastRadius caps the radius any of its scopes may target;
+ * mergePersonas() takes the maximum across inputs.
+ */
+export type BlastRadius = 'none' | 'read-only' | 'sandboxed' | 'destructive';
+export declare const BLAST_RADIUS_ORDER: readonly BlastRadius[];
+/**
+ * Constraint applied to a single tool argument by name.
+ * - `type` — required runtime type
+ * - `allowedValues` — enum of permitted literal values (when type === 'enum')
+ * - `pattern` — regex test for string args (rejected if it matches a
+ *   forbidden form; we use it as a *deny* pattern by convention — see check.ts)
+ * - `min` / `max` — numeric bounds (inclusive). For strings, applied to length.
+ */
+export interface ArgRule {
+    type: 'string' | 'number' | 'boolean' | 'enum';
+    allowedValues?: unknown[];
+    pattern?: RegExp;
+    /** When true, the regex acts as a *deny* pattern (match → reject). Defaults to false (must match). */
+    denyPattern?: boolean;
+    min?: number;
+    max?: number;
+}
+/**
+ * A single permission scope. Match against a tool name and a payload of args.
+ * - `toolPattern` — exact string match or RegExp test
+ * - `argConstraints` — keyed by argument name
+ * - `rateLimit` — sliding-window counter shared per (persona.id, toolName)
+ */
+export interface Scope {
+    toolPattern: string | RegExp;
+    argConstraints?: Record<string, ArgRule>;
+    rateLimit?: {
+        max: number;
+        windowMs: number;
+    };
+    /** Optional radius for this scope; cannot exceed Persona's maxBlastRadius. */
+    blastRadius?: BlastRadius;
+}
+/**
+ * Named, composable persona. `id` is the lookup key in the registry.
+ */
+export interface Persona {
+    id: string;
+    description: string;
+    scopes: Scope[];
+    maxBlastRadius?: BlastRadius;
+}
+export interface PermissionGrant {
+    persona: Persona;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+export interface Verdict {
+    allowed: boolean;
+    reason?: string;
+    matchedScope?: Scope;
+}
+/**
+ * Thrown by enforce(). Carries the full verdict for upstream logging.
+ */
+export declare class PermissionDeniedError extends Error {
+    readonly verdict: Verdict;
+    readonly grant: PermissionGrant;
+    constructor(grant: PermissionGrant, verdict: Verdict);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/futures/persona/types.js

@@ -0,0 +1,28 @@
+// futures/persona/types — type-checked privilege scoping for tool invocation.
+//
+// A Persona is a named bundle of Scopes. A Scope binds a tool pattern to a
+// set of argument constraints, an optional rate limit, and is bounded by
+// the Persona's max blast radius. canInvoke() resolves a (persona, tool, args)
+// triple to a Verdict. enforce() turns a denied Verdict into a thrown error.
+//
+// Module is standalone — no integration into permissions.ts yet.
+export const BLAST_RADIUS_ORDER = [
+    'none',
+    'read-only',
+    'sandboxed',
+    'destructive',
+];
+/**
+ * Thrown by enforce(). Carries the full verdict for upstream logging.
+ */
+export class PermissionDeniedError extends Error {
+    verdict;
+    grant;
+    constructor(grant, verdict) {
+        super(`permission denied: persona=${grant.persona.id} tool=${grant.toolName} reason=${verdict.reason ?? 'no scope matched'}`);
+        this.name = 'PermissionDeniedError';
+        this.verdict = verdict;
+        this.grant = grant;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/futures/skill-graph/graph.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Skill graph — runtime ops.
+ *
+ * Pure functions over the SkillGraph data structure. Mutators return new
+ * instances rather than mutating in place; the underlying Maps and arrays
+ * are copied. Random walks use a seeded LCG for deterministic tests.
+ */
+import type { Edge, GraphPath, Scenario, Skill, SkillGraph } from './types.js';
+export declare function buildGraph(): SkillGraph;
+export declare function addSkill(g: SkillGraph, skill: Skill): SkillGraph;
+export declare function addScenario(g: SkillGraph, scenario: Scenario): SkillGraph;
+export declare function addEdge(g: SkillGraph, edge: Edge): SkillGraph;
+export interface SampleOptions {
+    start?: string;
+    maxLength?: number;
+    seed?: number;
+}
+export declare function samplePath(g: SkillGraph, opts?: SampleOptions): GraphPath;
+export declare function findPaths(g: SkillGraph, fromId: string, toId: string, maxDepth?: number): GraphPath[];
+export interface PathLengthStats {
+    min: number;
+    max: number;
+    avg: number;
+    p50: number;
+    p95: number;
+    samples: number;
+}
+export declare function pathLengthDistribution(g: SkillGraph, samples?: number, opts?: {
+    seed?: number;
+}): PathLengthStats;
+//# sourceMappingURL=graph.d.ts.map

package/dist/futures/skill-graph/graph.js

@@ -0,0 +1,151 @@
+/**
+ * Skill graph — runtime ops.
+ *
+ * Pure functions over the SkillGraph data structure. Mutators return new
+ * instances rather than mutating in place; the underlying Maps and arrays
+ * are copied. Random walks use a seeded LCG for deterministic tests.
+ */
+function lcg(seed) {
+    let state = seed >>> 0;
+    return {
+        next() {
+            state = (state * 1664525 + 1013904223) >>> 0;
+            return state / 0xffffffff;
+        },
+    };
+}
+function defaultRng() {
+    return { next: () => Math.random() };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Construction
+// ─────────────────────────────────────────────────────────────────────────────
+export function buildGraph() {
+    return {
+        skills: new Map(),
+        scenarios: new Map(),
+        edges: [],
+    };
+}
+export function addSkill(g, skill) {
+    const next = new Map(g.skills);
+    next.set(skill.id, skill);
+    return { ...g, skills: next };
+}
+export function addScenario(g, scenario) {
+    const next = new Map(g.scenarios);
+    next.set(scenario.id, scenario);
+    return { ...g, scenarios: next };
+}
+export function addEdge(g, edge) {
+    return { ...g, edges: [...g.edges, edge] };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Lookup helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function getNode(g, id) {
+    return g.skills.get(id) ?? g.scenarios.get(id);
+}
+function outgoing(g, fromId) {
+    return g.edges.filter((e) => e.from === fromId);
+}
+export function samplePath(g, opts = {}) {
+    const rng = opts.seed !== undefined ? lcg(opts.seed) : defaultRng();
+    const maxLength = opts.maxLength ?? 6;
+    const startId = opts.start ?? pickStartNode(g, rng);
+    if (!startId)
+        return { nodes: [], edges: [], pathLength: 0 };
+    const startNode = getNode(g, startId);
+    if (!startNode)
+        return { nodes: [], edges: [], pathLength: 0 };
+    const nodes = [startNode];
+    const edges = [];
+    const visited = new Set([startId]);
+    let currentId = startId;
+    while (nodes.length < maxLength) {
+        const candidates = outgoing(g, currentId).filter((e) => !visited.has(e.to));
+        if (candidates.length === 0)
+            break;
+        const edge = weightedPick(candidates, rng);
+        const nextNode = getNode(g, edge.to);
+        if (!nextNode)
+            break;
+        edges.push(edge);
+        nodes.push(nextNode);
+        visited.add(edge.to);
+        currentId = edge.to;
+    }
+    return { nodes, edges, pathLength: nodes.length };
+}
+function pickStartNode(g, rng) {
+    const all = [...g.skills.keys(), ...g.scenarios.keys()];
+    if (all.length === 0)
+        return undefined;
+    return all[Math.floor(rng.next() * all.length)];
+}
+function weightedPick(edges, rng) {
+    const total = edges.reduce((s, e) => s + (e.weight ?? 1), 0);
+    let pick = rng.next() * total;
+    for (const edge of edges) {
+        pick -= edge.weight ?? 1;
+        if (pick <= 0)
+            return edge;
+    }
+    return edges[edges.length - 1];
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Path finding — DFS with depth limit
+// ─────────────────────────────────────────────────────────────────────────────
+export function findPaths(g, fromId, toId, maxDepth = 5) {
+    const startNode = getNode(g, fromId);
+    if (!startNode)
+        return [];
+    const results = [];
+    const stack = [
+        { id: fromId, nodes: [startNode], edges: [] },
+    ];
+    while (stack.length > 0) {
+        const { id, nodes, edges } = stack.pop();
+        if (id === toId && nodes.length > 1) {
+            results.push({ nodes, edges, pathLength: nodes.length });
+            continue;
+        }
+        if (nodes.length >= maxDepth)
+            continue;
+        const visited = new Set(nodes.map((n) => n.id));
+        for (const edge of outgoing(g, id)) {
+            if (visited.has(edge.to))
+                continue;
+            const next = getNode(g, edge.to);
+            if (!next)
+                continue;
+            stack.push({
+                id: edge.to,
+                nodes: [...nodes, next],
+                edges: [...edges, edge],
+            });
+        }
+    }
+    return results;
+}
+export function pathLengthDistribution(g, samples = 100, opts = {}) {
+    if (samples <= 0) {
+        return { min: 0, max: 0, avg: 0, p50: 0, p95: 0, samples: 0 };
+    }
+    const baseSeed = opts.seed ?? Date.now();
+    const lengths = [];
+    for (let i = 0; i < samples; i++) {
+        const path = samplePath(g, { seed: baseSeed + i });
+        lengths.push(path.pathLength);
+    }
+    lengths.sort((a, b) => a - b);
+    const min = lengths[0] ?? 0;
+    const max = lengths[lengths.length - 1] ?? 0;
+    const sum = lengths.reduce((s, n) => s + n, 0);
+    const avg = sum / lengths.length;
+    const p50 = lengths[Math.floor(lengths.length * 0.5)] ?? 0;
+    const p95Idx = Math.min(lengths.length - 1, Math.floor(lengths.length * 0.95));
+    const p95 = lengths[p95Idx] ?? 0;
+    return { min, max, avg, p50, p95, samples };
+}
+//# sourceMappingURL=graph.js.map

package/dist/futures/skill-graph/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public surface for the skill-graph module.
+ *
+ * Tencent Hunyuan SkillSynth-style graph formalism over kbot's skill set.
+ * Path sampling produces synthetic Tasks for the harness/ evolution loop.
+ */
+export type { Edge, GraphPath, Scenario, Skill, SkillGraph, } from './types.js';
+export { isSkill } from './types.js';
+export { buildGraph, addSkill, addScenario, addEdge, samplePath, findPaths, pathLengthDistribution, } from './graph.js';
+export type { SampleOptions, PathLengthStats } from './graph.js';
+export { pathToTask } from './synthesis.js';
+export type { PathToTaskOptions } from './synthesis.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/futures/skill-graph/index.js

@@ -0,0 +1,10 @@
+/**
+ * Public surface for the skill-graph module.
+ *
+ * Tencent Hunyuan SkillSynth-style graph formalism over kbot's skill set.
+ * Path sampling produces synthetic Tasks for the harness/ evolution loop.
+ */
+export { isSkill } from './types.js';
+export { buildGraph, addSkill, addScenario, addEdge, samplePath, findPaths, pathLengthDistribution, } from './graph.js';
+export { pathToTask } from './synthesis.js';
+//# sourceMappingURL=index.js.map

package/dist/futures/skill-graph/synthesis.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Skill graph → synthetic task synthesis.
+ *
+ * Translates a sampled GraphPath into a Task instance compatible with the
+ * harness module's `Task` interface. The acceptance criteria are derived
+ * from the path's edges; the instructions describe the workflow in human-
+ * readable form.
+ */
+import type { Task } from '../harness/types.js';
+import type { GraphPath } from './types.js';
+export interface PathToTaskOptions {
+    /** Optional id prefix; defaults to "synth-". */
+    prefix?: string;
+    /** Optional context line prepended to instructions. */
+    contextHeader?: string;
+    /** Extra metadata to merge into Task.meta. */
+    meta?: Record<string, unknown>;
+}
+export declare function pathToTask(path: GraphPath, opts?: PathToTaskOptions): Task;
+//# sourceMappingURL=synthesis.d.ts.map

package/dist/futures/skill-graph/synthesis.js

@@ -0,0 +1,83 @@
+/**
+ * Skill graph → synthetic task synthesis.
+ *
+ * Translates a sampled GraphPath into a Task instance compatible with the
+ * harness module's `Task` interface. The acceptance criteria are derived
+ * from the path's edges; the instructions describe the workflow in human-
+ * readable form.
+ */
+export function pathToTask(path, opts = {}) {
+    const prefix = opts.prefix ?? 'synth-';
+    const id = `${prefix}${shortHash(path)}`;
+    const instructions = buildInstructions(path, opts.contextHeader);
+    const acceptance = buildAcceptance(path);
+    const meta = {
+        source: 'skill-graph',
+        pathLength: path.pathLength,
+        nodeIds: path.nodes.map((n) => n.id),
+        ...opts.meta,
+    };
+    return { id, instructions, acceptance, meta };
+}
+function buildInstructions(path, header) {
+    const parts = [];
+    if (header)
+        parts.push(header);
+    if (path.nodes.length === 0) {
+        parts.push('No nodes in path; nothing to do.');
+        return parts.join('\n\n');
+    }
+    parts.push(`Workflow with ${path.nodes.length} step(s):`);
+    path.nodes.forEach((node, i) => {
+        parts.push(`  ${i + 1}. ${describeNode(node)}`);
+    });
+    if (path.edges.length > 0) {
+        parts.push('');
+        parts.push('Transitions:');
+        path.edges.forEach((edge) => {
+            parts.push(`  - ${edge.from} → ${edge.to} (${edge.kind})`);
+        });
+    }
+    return parts.join('\n');
+}
+function buildAcceptance(path) {
+    if (path.nodes.length === 0)
+        return ['No nodes to verify.'];
+    const criteria = [];
+    for (const node of path.nodes) {
+        if (isSkillNode(node)) {
+            const tool = node.toolName ? ` (${node.toolName})` : '';
+            criteria.push(`Skill exercised: ${node.description}${tool}`);
+        }
+        else {
+            criteria.push(`Scenario context entered: ${node.description}`);
+        }
+    }
+    for (const edge of path.edges) {
+        if (edge.kind === 'requires') {
+            criteria.push(`Prerequisite satisfied: ${edge.from} before ${edge.to}`);
+        }
+    }
+    return criteria;
+}
+function describeNode(node) {
+    if (isSkillNode(node)) {
+        return node.toolName
+            ? `${node.description} (tool: ${node.toolName})`
+            : node.description;
+    }
+    return `${node.description}${node.tags?.length ? ` [${node.tags.join(', ')}]` : ''}`;
+}
+function isSkillNode(node) {
+    return !('tags' in node);
+}
+function shortHash(path) {
+    // Simple deterministic hash over node ids; not crypto.
+    const key = path.nodes.map((n) => n.id).join('|');
+    let h = 0;
+    for (let i = 0; i < key.length; i++) {
+        h = (h * 31 + key.charCodeAt(i)) >>> 0;
+    }
+    return h.toString(36).slice(0, 8);
+}
+//# sourceMappingURL=synthesis.js.map

package/dist/futures/skill-graph/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Skill graph — explicit graph formalism over skills + scenarios.
+ *
+ * Maps onto Tencent Hunyuan's "Toward Scalable Terminal Task Synthesis via
+ * Skill Graphs" (arXiv:2604.25727). Wraps the Bayesian flat-skill ratings in
+ * `packages/skill-router/` with structure: skill nodes, scenario nodes
+ * (intermediate workflow contexts), and weighted edges between them.
+ *
+ * A path through the graph is a candidate workflow. Sampling paths produces
+ * synthetic Tasks (compatible with `harness/types.ts`) for evaluation and
+ * training.
+ *
+ * This module is types-only. Runtime lives in graph.ts and synthesis.ts.
+ */
+/** A skill node — typically maps 1:1 to a registered kbot tool. */
+export interface Skill {
+    id: string;
+    description: string;
+    /** Optional name of the underlying tool (from packages/kbot/src/tools/). */
+    toolName?: string;
+}
+/**
+ * A scenario node — an intermediate workflow context that connects skills.
+ * Example: "after-cloning-a-repo", "in-an-ableton-set", "researching-a-paper".
+ */
+export interface Scenario {
+    id: string;
+    description: string;
+    tags?: string[];
+}
+/** A directed edge between two nodes (skill or scenario). */
+export interface Edge {
+    from: string;
+    to: string;
+    /** Sampling weight; defaults to 1. Higher = more likely on a random walk. */
+    weight?: number;
+    kind: 'invokes' | 'follows' | 'requires';
+}
+/** Result of a graph traversal: ordered nodes + edges + length. */
+export interface GraphPath {
+    nodes: Array<Skill | Scenario>;
+    edges: Edge[];
+    pathLength: number;
+}
+/** Immutable-ish graph container. Mutators return new instances. */
+export interface SkillGraph {
+    skills: Map<string, Skill>;
+    scenarios: Map<string, Scenario>;
+    edges: Edge[];
+}
+/** Type guard: skill vs scenario. */
+export declare function isSkill(node: Skill | Scenario): node is Skill;
+//# sourceMappingURL=types.d.ts.map

package/dist/futures/skill-graph/types.js

@@ -0,0 +1,19 @@
+/**
+ * Skill graph — explicit graph formalism over skills + scenarios.
+ *
+ * Maps onto Tencent Hunyuan's "Toward Scalable Terminal Task Synthesis via
+ * Skill Graphs" (arXiv:2604.25727). Wraps the Bayesian flat-skill ratings in
+ * `packages/skill-router/` with structure: skill nodes, scenario nodes
+ * (intermediate workflow contexts), and weighted edges between them.
+ *
+ * A path through the graph is a candidate workflow. Sampling paths produces
+ * synthetic Tasks (compatible with `harness/types.ts`) for evaluation and
+ * training.
+ *
+ * This module is types-only. Runtime lives in graph.ts and synthesis.ts.
+ */
+/** Type guard: skill vs scenario. */
+export function isSkill(node) {
+    return 'description' in node && !('tags' in node) && !('id' in node && node.tags !== undefined);
+}
+//# sourceMappingURL=types.js.map

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernel.chat/kbot",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Open-source terminal AI agent. 100+ specialist skills, 35 specialist agents, 20 providers. Dreams, learns, watches your system. Controls your phone. Fully local, fully sovereign. MIT. v4.0 — evidence-based curation.",
   "type": "module",
   "repository": {