om-memory-system 4.29.1 → 4.31.1

package/dist/services/skill-learning/skill-config.js

@@ -0,0 +1,70 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+function expandHome(path, homeDir) {
+    return path.startsWith("~/") || path.startsWith("~\\") ? join(homeDir, path.slice(2)) : path;
+}
+function checkedBoolean(value, key, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "boolean")
+        throw new Error(`Invalid ${key} config`);
+    return value;
+}
+/**
+ * Validate `skillFolders`: absolute paths or paths that start with `~/`,
+ * expanded and de-duplicated. Throws on the first invalid entry, like the
+ * other list settings. Whether a folder exists is checked when the setting is
+ * saved, not here, so a folder on a drive that is not mounted does not break
+ * the config.
+ */
+function parseSkillFolders(value, homeDir) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new Error("Invalid skillFolders config: must be a list");
+    const folders = value.map((entry, index) => {
+        const trimmed = typeof entry === "string" ? entry.trim() : "";
+        const expanded = expandHome(trimmed, homeDir);
+        if (!trimmed || !isAbsolute(expanded)) {
+            throw new Error(`Invalid skillFolders config: entry ${index} needs an absolute path or a path that starts with ~/`);
+        }
+        return resolve(expanded);
+    });
+    return [...new Set(folders)];
+}
+/** The three settings from a merged file config, with defaults applied. */
+export function normaliseSkillConfig(fileConfig, homeDir = homedir()) {
+    return {
+        skillLearning: checkedBoolean(fileConfig.skillLearning, "skillLearning", false),
+        skillLearningRedact: checkedBoolean(fileConfig.skillLearningRedact, "skillLearningRedact", true),
+        skillFolders: parseSkillFolders(fileConfig.skillFolders, homeDir),
+    };
+}
+/**
+ * The first `skillFolders` entry, as written, that is not an existing folder,
+ * or null when every entry is one. The Settings save refuses a missing folder
+ * and names it. `isFolder` is passed in so the caller owns the file system access.
+ */
+export function missingSkillFolder(folders, isFolder, homeDir = homedir()) {
+    return folders.find((folder) => !isFolder(resolve(expandHome(folder.trim(), homeDir)))) ?? null;
+}
+/**
+ * What a project config may change. A checked-in project file must not start
+ * recording conversations, so it can only turn `skillLearning` off. Its
+ * `skillLearningRedact` and `skillFolders` are always ignored.
+ * `ignoredTurnOn` tells the caller to log a project value of `true`.
+ */
+export function projectSkillOverride(project) {
+    return {
+        override: project.skillLearning === false ? { skillLearning: false } : {},
+        ignoredTurnOn: project.skillLearning === true,
+    };
+}
+/**
+ * The folders to watch when `skillFolders` is unset: `~/.agents/skills` and
+ * `<Claude Code folder>/skills`, each only when it exists. `exists` is passed
+ * in so the caller owns the file system access.
+ */
+export function defaultSkillFolders(homeDir, claudeFolder, exists) {
+    return [join(homeDir, ".agents", "skills"), join(claudeFolder, "skills")].filter(exists);
+}

package/dist/services/skill-learning/skill-detect.d.ts

@@ -0,0 +1,29 @@
+import type { SkillIndex } from "./skill-index.js";
+import type { SkillUseRow } from "./store.js";
+/** The parts of a work unit that skill detection reads. */
+export interface SkillDetectInput {
+    prompt: string;
+    toolCalls: ReadonlyArray<DetectToolCall>;
+}
+/** `path` is the full read path the host readers keep; `input` can be cut. */
+interface DetectToolCall {
+    name: string;
+    input: string;
+    path?: string;
+}
+/**
+ * Reads one string field from a tool input as the host readers format it:
+ * `key: "value", key2: ...` (Claude Code, Pi, OpenCode live) or JSON
+ * (OpenCode import). Inputs can be cut at 100 characters, so this does not
+ * parse the whole string.
+ */
+export declare function toolInputField(input: string, key: string): string | null;
+/**
+ * Finds the skills a turn used. `tool`: the host's skill tool loaded it.
+ * `read`: a read tool opened a `SKILL.md` inside a watched folder.
+ * `command`: the prompt invoked a known skill by its slash form.
+ * Each skill is listed once per method. `position` is the index of the tool
+ * call that loaded the skill (the first one for a repeat), and -1 for `command`.
+ */
+export declare function detectSkillUses(unit: SkillDetectInput, index: SkillIndex): SkillUseRow[];
+export {};

package/dist/services/skill-learning/skill-detect.js

@@ -0,0 +1,130 @@
+import { homedir } from "node:os";
+import { basename, dirname, resolve, sep } from "node:path";
+import { realPathOrSelf } from "./skill-folders.js";
+const READ_TOOLS = new Set(["read", "view"]);
+const READ_PATH_KEYS = ["file_path", "filePath", "path"];
+/**
+ * Reads one string field from a tool input as the host readers format it:
+ * `key: "value", key2: ...` (Claude Code, Pi, OpenCode live) or JSON
+ * (OpenCode import). Inputs can be cut at 100 characters, so this does not
+ * parse the whole string.
+ */
+export function toolInputField(input, key) {
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`(?:^|[,{]\\s*)"?${escaped}"?\\s*:\\s*("(?:[^"\\\\]|\\\\.)*")`);
+    const match = pattern.exec(input);
+    if (!match)
+        return null;
+    try {
+        const value = JSON.parse(match[1]);
+        return typeof value === "string" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function byName(index, name) {
+    return index.entries.filter((entry) => entry.name === name);
+}
+/**
+ * A `plugin:skill` name matches a watched skill on the part after the colon.
+ * Otherwise it keeps its full form, so a command such as `opsx:apply` is not shown as `apply`.
+ */
+function skillName(name, index) {
+    const trimmed = name.trim();
+    const bare = trimmed.slice(trimmed.lastIndexOf(":") + 1);
+    return byName(index, bare).length > 0 ? bare : trimmed;
+}
+/** A path only when the name points at exactly one skill. */
+function pathFor(index, name) {
+    const found = byName(index, name);
+    return found.length === 1 ? found[0].path : null;
+}
+function skillToolName(call) {
+    if (call.name === "Skill")
+        return toolInputField(call.input, "skill");
+    if (call.name === "skill")
+        return toolInputField(call.input, "name");
+    return null;
+}
+function expandHome(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/"))
+        return resolve(homedir(), path.slice(2));
+    return path;
+}
+function insideFolder(path, folder) {
+    const root = resolve(expandHome(folder));
+    return path.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+function readSkillUse(call, index) {
+    if (!READ_TOOLS.has(call.name.toLowerCase()))
+        return null;
+    // Prefer the full path; the input text is cut at 100 characters.
+    const candidates = call.path !== undefined
+        ? [call.path]
+        : READ_PATH_KEYS.map((key) => toolInputField(call.input, key));
+    for (const raw of candidates) {
+        if (!raw || !/[\\/]SKILL\.md$/.test(raw))
+            continue;
+        const path = resolve(expandHome(raw));
+        // A read through a linked folder matches the indexed file by its real path.
+        const real = realPathOrSelf(path);
+        const entry = index.entries.find((e) => resolve(expandHome(e.path)) === path) ??
+            index.entries.find((e) => realPathOrSelf(e.path) === real);
+        if (entry)
+            return { name: entry.name, path: entry.path, method: "read" };
+        if (!index.folders.some((folder) => insideFolder(path, folder)))
+            return null;
+        return { name: basename(dirname(path)), path, method: "read" };
+    }
+    return null;
+}
+/** The skill names a prompt invokes by its slash form. Unknown names are left to the caller. */
+function commandNames(prompt, index) {
+    const names = [];
+    const lead = /^\/([\w:.-]+)(?:\s|$)/.exec(prompt.trimStart());
+    if (lead)
+        names.push(skillName(lead[1], index));
+    for (const match of prompt.matchAll(/<command-name>\s*\/([\w:.-]+)\s*<\/command-name>/g)) {
+        names.push(skillName(match[1], index));
+    }
+    return names;
+}
+/**
+ * Finds the skills a turn used. `tool`: the host's skill tool loaded it.
+ * `read`: a read tool opened a `SKILL.md` inside a watched folder.
+ * `command`: the prompt invoked a known skill by its slash form.
+ * Each skill is listed once per method. `position` is the index of the tool
+ * call that loaded the skill (the first one for a repeat), and -1 for `command`.
+ */
+export function detectSkillUses(unit, index) {
+    const uses = [];
+    const seen = new Set();
+    const add = (use) => {
+        const key = `${use.method}\u0000${use.name}\u0000${use.path ?? ""}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        uses.push(use);
+    };
+    for (const name of commandNames(unit.prompt, index)) {
+        if (byName(index, name).length > 0) {
+            add({ name, path: pathFor(index, name), method: "command", position: -1 });
+        }
+    }
+    for (const [position, call] of unit.toolCalls.entries()) {
+        const toolName = skillToolName(call);
+        if (toolName) {
+            const name = skillName(toolName, index);
+            if (name)
+                add({ name, path: pathFor(index, name), method: "tool", position });
+            continue;
+        }
+        const read = readSkillUse(call, index);
+        if (read)
+            add({ ...read, position });
+    }
+    return uses;
+}

package/dist/services/skill-learning/skill-folders.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The watched skill folders, in one place for every caller. The caller passes
+ * `CONFIG`, because many tests stub `src/config.js`.
+ */
+/** The real path, or the path as given when it does not exist. */
+export declare function realPathOrSelf(path: string): string;
+/**
+ * `skillFolders`, or the default folders when it is unset. Folders with the
+ * same real path, such as `~/.claude/skills` linked to `~/.agents/skills`,
+ * are watched once, under the first spelling.
+ */
+export declare function watchedSkillFolders(config: {
+    skillFolders?: string[];
+    claudeConfigDir?: string;
+}): string[];
+/**
+ * Where `skills.db` lives: the global `storagePath`, never a project value.
+ * `initConfig` sets `skillStoragePath` only when a project config moved
+ * `storagePath`; otherwise `storagePath` is the global one.
+ */
+export declare function skillStoragePath(config: {
+    storagePath: string;
+    skillStoragePath?: string;
+}): string;

package/dist/services/skill-learning/skill-folders.js

@@ -0,0 +1,42 @@
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolveClaudeFolder } from "../claude-folder.js";
+import { defaultSkillFolders } from "./skill-config.js";
+/**
+ * The watched skill folders, in one place for every caller. The caller passes
+ * `CONFIG`, because many tests stub `src/config.js`.
+ */
+/** The real path, or the path as given when it does not exist. */
+export function realPathOrSelf(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * `skillFolders`, or the default folders when it is unset. Folders with the
+ * same real path, such as `~/.claude/skills` linked to `~/.agents/skills`,
+ * are watched once, under the first spelling.
+ */
+export function watchedSkillFolders(config) {
+    const folders = config.skillFolders ??
+        defaultSkillFolders(homedir(), resolveClaudeFolder(config.claudeConfigDir).folder, existsSync);
+    const seen = new Set();
+    return folders.filter((folder) => {
+        const real = realPathOrSelf(folder);
+        if (seen.has(real))
+            return false;
+        seen.add(real);
+        return true;
+    });
+}
+/**
+ * Where `skills.db` lives: the global `storagePath`, never a project value.
+ * `initConfig` sets `skillStoragePath` only when a project config moved
+ * `storagePath`; otherwise `storagePath` is the global one.
+ */
+export function skillStoragePath(config) {
+    return config.skillStoragePath ?? config.storagePath;
+}

package/dist/services/skill-learning/skill-index.d.ts

@@ -0,0 +1,28 @@
+/** How many folder levels below a watched folder are searched for `SKILL.md`. */
+export declare const SKILL_INDEX_MAX_DEPTH = 4;
+export declare const SKILL_INDEX_CACHE_MS = 60000;
+export interface SkillIndexEntry {
+    /** The front matter `name`, or the folder name when the front matter has none. */
+    name: string;
+    /** Full path of the `SKILL.md` file. */
+    path: string;
+    /** The watched folder the skill was found in. */
+    folder: string;
+    description: string;
+}
+export interface SkillIndex {
+    folders: string[];
+    /** Every skill found. Two skills can share a name; both are kept. */
+    entries: SkillIndexEntry[];
+}
+/** Reads top-level `key: value` pairs from YAML front matter. Folded values join their lines. */
+export declare function readFrontMatter(text: string): Record<string, string>;
+/**
+ * Lists every `SKILL.md` up to four folder levels below each watched folder.
+ * A file reached twice through a link is listed once, under its first path. No cache.
+ */
+export declare function buildSkillIndex(folders: readonly string[]): SkillIndex;
+/** The index for these folders, rebuilt when it is older than 60 seconds or the list changes. */
+export declare function getSkillIndex(folders: readonly string[], now?: number): SkillIndex;
+/** Drops the cached index, for example after OMMS writes a skill file. */
+export declare function clearSkillIndexCache(): void;

package/dist/services/skill-learning/skill-index.js

@@ -0,0 +1,118 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { realPathOrSelf } from "./skill-folders.js";
+/** How many folder levels below a watched folder are searched for `SKILL.md`. */
+export const SKILL_INDEX_MAX_DEPTH = 4;
+export const SKILL_INDEX_CACHE_MS = 60_000;
+const SKIP_FOLDERS = new Set([".git", "node_modules"]);
+function unquote(value) {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2 &&
+        (trimmed[0] === '"' || trimmed[0] === "'") &&
+        trimmed[trimmed.length - 1] === trimmed[0]) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+/** Reads top-level `key: value` pairs from YAML front matter. Folded values join their lines. */
+export function readFrontMatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (!match)
+        return {};
+    const fields = {};
+    const lines = match[1].split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const field = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(lines[i]);
+        if (!field)
+            continue;
+        let value = field[2].trim();
+        if (value === "" || /^[>|][+-]?$/.test(value)) {
+            const block = [];
+            while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1]))
+                block.push(lines[++i].trim());
+            value = block.join(" ");
+        }
+        fields[field[1]] = unquote(value);
+    }
+    return fields;
+}
+function isDirectory(path) {
+    try {
+        // statSync follows links, so linked skill folders are searched too.
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function readEntry(path, folder) {
+    let fields = {};
+    try {
+        fields = readFrontMatter(readFileSync(path, "utf8"));
+    }
+    catch {
+        // An unreadable file still names a skill by its folder.
+    }
+    return {
+        name: fields.name || basename(dirname(path)),
+        path,
+        folder,
+        description: fields.description ?? "",
+    };
+}
+function walk(dir, depth, folder, out) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    if (names.includes("SKILL.md"))
+        out.push(readEntry(join(dir, "SKILL.md"), folder));
+    if (depth >= SKILL_INDEX_MAX_DEPTH)
+        return;
+    for (const name of names.sort()) {
+        if (SKIP_FOLDERS.has(name))
+            continue;
+        const child = join(dir, name);
+        if (isDirectory(child))
+            walk(child, depth + 1, folder, out);
+    }
+}
+/**
+ * Lists every `SKILL.md` up to four folder levels below each watched folder.
+ * A file reached twice through a link is listed once, under its first path. No cache.
+ */
+export function buildSkillIndex(folders) {
+    const found = [];
+    for (const folder of folders) {
+        if (isDirectory(folder))
+            walk(folder, 0, folder, found);
+    }
+    const seen = new Set();
+    const entries = found.filter((entry) => {
+        const real = realPathOrSelf(entry.path);
+        if (seen.has(real))
+            return false;
+        seen.add(real);
+        return true;
+    });
+    return { folders: [...folders], entries };
+}
+const cache = new Map();
+/** The index for these folders, rebuilt when it is older than 60 seconds or the list changes. */
+export function getSkillIndex(folders, now = Date.now()) {
+    const key = JSON.stringify(folders);
+    const hit = cache.get(key);
+    if (hit && now - hit.builtAt < SKILL_INDEX_CACHE_MS)
+        return hit.index;
+    const index = buildSkillIndex(folders);
+    cache.clear();
+    cache.set(key, { builtAt: now, index });
+    return index;
+}
+/** Drops the cached index, for example after OMMS writes a skill file. */
+export function clearSkillIndexCache() {
+    cache.clear();
+}

package/dist/services/skill-learning/skill-model.d.ts

@@ -0,0 +1,10 @@
+import { type ChatRuntimeConfig } from "../chat/chat-runtime.js";
+import type { SkillModel } from "./drafting.js";
+/** A draft sends a whole SKILL.md and up to 60,000 characters of turns, so it gets longer than chat. */
+export declare const SKILL_MODEL_TIMEOUT_MS = 120000;
+/**
+ * The external API model through the chat's client and readiness check
+ * (ADR-033). Claude Code has no session model, so drafting uses this on
+ * every host. The caller passes `CONFIG`.
+ */
+export declare function skillModel(config: ChatRuntimeConfig): SkillModel;

package/dist/services/skill-learning/skill-model.js

@@ -0,0 +1,15 @@
+import { callTool } from "../chat/chat-runtime.js";
+import { chatStatus } from "../chat/chat-status.js";
+/** A draft sends a whole SKILL.md and up to 60,000 characters of turns, so it gets longer than chat. */
+export const SKILL_MODEL_TIMEOUT_MS = 120_000;
+/**
+ * The external API model through the chat's client and readiness check
+ * (ADR-033). Claude Code has no session model, so drafting uses this on
+ * every host. The caller passes `CONFIG`.
+ */
+export function skillModel(config) {
+    return {
+        ready: chatStatus(config).ready,
+        callTool: (system, user, tool) => callTool(config, system, user, tool, SKILL_MODEL_TIMEOUT_MS),
+    };
+}

package/dist/services/skill-learning/store.d.ts

@@ -0,0 +1,79 @@
+import type { TursoDb } from "../turso/turso-db.js";
+/** Bump when the tables change, and add the step to `init`. */
+export declare const SKILL_SCHEMA_VERSION = 1;
+export declare const SKILLS_DB_FILE = "skills.db";
+export type SkillToolOutcome = "ok" | "error" | "unknown";
+export type SkillUseMethod = "tool" | "read" | "command";
+export interface SkillToolCallRow {
+    name: string;
+    input: string;
+    outcome: SkillToolOutcome;
+    error: string | null;
+}
+export interface SkillUseRow {
+    name: string;
+    path: string | null;
+    method: SkillUseMethod;
+    /**
+     * Index of the tool call that loaded the skill, or -1 for a slash command
+     * (every tool call in the turn follows it). Missing or null: treated as -1.
+     */
+    position?: number | null;
+}
+/** One finished turn as it is written to `skills.db`. */
+export interface SkillTurnRecord {
+    /** `<host>:<session id>:<user message id>`. */
+    turnKey: string;
+    host: string;
+    sessionId: string;
+    projectTag: string | null;
+    projectName: string | null;
+    provider: string | null;
+    model: string | null;
+    createdAt: number;
+    prompt: string;
+    replies: string[];
+    redacted: boolean;
+    toolCalls: SkillToolCallRow[];
+    skillUses: SkillUseRow[];
+}
+export declare class SkillStoreError extends Error {
+    readonly code: "read_only";
+    constructor(message: string, code: "read_only");
+}
+type GetConnection = (dbPath: string) => Promise<TursoDb>;
+/** `skills.db` always sits in the global storage path, never in a project folder. */
+export declare function skillsDbPath(storagePath: string): string;
+/**
+ * Recorded turns, proposals and saved versions in `skills.db`. One instance
+ * per file. Writes check the schema version, so a file from a newer OMMS
+ * stays untouched. Reads on a missing file return empty values and do not
+ * create the file.
+ */
+export declare class SkillStore {
+    private readonly dbPath;
+    private readonly connect;
+    private readOnly;
+    constructor(dbPath: string, connect?: GetConnection);
+    /** The open connection. `proposal-store.ts` and `ranking.ts` share it. */
+    db(): Promise<TursoDb>;
+    /** Creates or upgrades the tables. Call it before any write. */
+    init(): Promise<void>;
+    isReadOnly(): boolean;
+    private writable;
+    /** Opens the file only when it and the `turns` table exist, so a read never creates it. */
+    existingDb(): Promise<TursoDb | null>;
+    /**
+     * Writes the turn, its tool calls and its skill uses in one transaction.
+     * Returns false when the `turn_key` is already stored; nothing is written then.
+     */
+    insertTurn(turn: SkillTurnRecord): Promise<boolean>;
+    /** Read-only lookup; a missing file gives false and stays missing. */
+    hasTurn(turnKey: string): Promise<boolean>;
+    countTurns(): Promise<number>;
+    /** Deletes every turn with its tool calls and skill uses. Proposals and versions stay. */
+    deleteAllTurns(): Promise<number>;
+    /** Size of `skills.db` in bytes, or 0 when the file does not exist. */
+    fileSize(): number;
+}
+export {};