@kernel.chat/kbot 4.0.1 → 4.1.0

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

@@ -1,6 +1,6 @@
 {
   "name": "@kernel.chat/kbot",
-  "version": "4.0.1",
+  "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": {