gisool 0.0.0-stage → 0.1.0

package/dist/packs/gemini.js

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { isObject, isRemoteEntry, noop, planJsonFile, readJsonConfig, refuse } from "./json-config.js";
+// Hook shape confirmed against https://geminicli.com/docs/hooks/ : settings.json "hooks" maps an event name to groups
+// of { matcher?, hooks: [{ type: "command", name, command, timeout }] }; timeout is in milliseconds. BeforeAgent is a
+// lifecycle event (exact-string matcher, so none is written); AfterTool matchers are regular expressions over tool names.
+const HOOK_NAME = "gisool-capture";
+const HOOK_TIMEOUT_MS = 5000;
+const HOOK_EVENTS = [{ event: "BeforeAgent" }, { event: "AfterTool", matcher: "activate_skill" }];
+const URL_KEYS = ["httpUrl", "url"];
+function localMcpUrl(port) {
+    return `http://127.0.0.1:${port}/mcp`;
+}
+function hookCommand(ctx) {
+    return `"${ctx.nodePath}" "${join(ctx.packageRoot, "packs", "hook-post.mjs")}" gemini`;
+}
+function isOurHookGroup(group) {
+    return (isObject(group) &&
+        Array.isArray(group.hooks) &&
+        group.hooks.some((h) => isObject(h) && typeof h.command === "string" && h.command.endsWith('hook-post.mjs" gemini')));
+}
+export const geminiPack = {
+    id: "gemini",
+    async detect({ home }) {
+        const dir = join(home, ".gemini");
+        const installed = existsSync(dir);
+        const servers = readJsonConfig(join(dir, "settings.json")).obj.mcpServers;
+        return {
+            installed,
+            evidence: installed ? [dir] : [],
+            remoteGisulRegistered: isObject(servers) && isRemoteEntry(servers.gisul, URL_KEYS),
+        };
+    },
+    async plan(ctx) {
+        const dir = join(ctx.home, ".gemini");
+        if (!existsSync(dir))
+            return noop("~/.gemini not found; Gemini CLI does not appear to be installed, nothing planned.");
+        const path = join(dir, "settings.json");
+        const current = readJsonConfig(path);
+        if (current.error)
+            return refuse(path, "unparseable_config", current.error);
+        const next = structuredClone(current.obj);
+        const servers = next.mcpServers ?? {};
+        const hooks = next.hooks ?? {};
+        if (!isObject(servers) || !isObject(hooks))
+            return refuse(path, "invalid_shape", "mcpServers and hooks must be JSON objects");
+        const notes = [];
+        if (ctx.disableRemote && isRemoteEntry(servers.gisul, URL_KEYS)) {
+            notes.push("Remote gisul MCP entry left enabled: Gemini's disable key is unverified, so disable it manually.");
+        }
+        servers.gisool = { httpUrl: localMcpUrl(ctx.port), headers: { Authorization: `Bearer ${ctx.token}` } };
+        next.mcpServers = servers;
+        for (const { event, matcher } of HOOK_EVENTS) {
+            const groups = hooks[event] ?? [];
+            if (!Array.isArray(groups))
+                return refuse(path, "invalid_shape", `hooks.${event} must be an array`);
+            const ours = {
+                ...(matcher ? { matcher } : {}),
+                hooks: [{ type: "command", name: HOOK_NAME, command: hookCommand(ctx), timeout: HOOK_TIMEOUT_MS }],
+            };
+            hooks[event] = [...groups.filter((group) => !isOurHookGroup(group)), ours];
+        }
+        next.hooks = hooks;
+        const file = planJsonFile(path, current, next);
+        notes.push("Restart Gemini CLI to load the gisool MCP server and capture hooks.");
+        return { files: file ? [file] : [], commands: [], notes, conflicts: [] };
+    },
+    async doctorChecks({ home, port }) {
+        const current = readJsonConfig(join(home, ".gemini", "settings.json"));
+        if (current.error)
+            return [{ name: "gemini settings.json", ok: false, detail: current.error }];
+        const servers = isObject(current.obj.mcpServers) ? current.obj.mcpServers : {};
+        const entry = isObject(servers.gisool) ? servers.gisool : {};
+        const hooks = isObject(current.obj.hooks) ? current.obj.hooks : {};
+        const hooksPresent = HOOK_EVENTS.every(({ event }) => {
+            const groups = hooks[event];
+            return Array.isArray(groups) && groups.some(isOurHookGroup);
+        });
+        return [
+            { name: "gemini MCP gisool", ok: entry.httpUrl === localMcpUrl(port), detail: `httpUrl ${String(entry.httpUrl ?? "missing")}` },
+            {
+                name: "gemini capture hooks",
+                ok: hooksPresent,
+                detail: hooksPresent ? "BeforeAgent and AfterTool present" : "capture hooks missing; rerun gisool init",
+            },
+        ];
+    },
+};

package/dist/packs/json-config.js

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function readJsonConfig(path) {
+    if (!existsSync(path))
+        return { before: null, obj: {} };
+    const before = readFileSync(path, "utf8");
+    if (before.trim() === "")
+        return { before, obj: {} };
+    try {
+        const parsed = JSON.parse(before);
+        if (isObject(parsed))
+            return { before, obj: parsed };
+        return { before, obj: {}, error: "top-level value is not a JSON object" };
+    }
+    catch (err) {
+        return { before, obj: {}, error: `not valid JSON: ${err.message}` };
+    }
+}
+export function fileMode(path) {
+    return existsSync(path) ? statSync(path).mode & 0o777 : 0o600;
+}
+export function planJsonFile(path, current, next) {
+    const after = `${JSON.stringify(next, null, 2)}\n`;
+    if (after === current.before)
+        return null;
+    return { path, before: current.before, after, mode: fileMode(path) };
+}
+export function refuse(path, code, detail) {
+    return { files: [], commands: [], notes: [], conflicts: [{ path, code, detail }] };
+}
+export function noop(note) {
+    return { files: [], commands: [], notes: [note], conflicts: [] };
+}
+export function isRemoteEntry(entry, urlKeys) {
+    if (!isObject(entry))
+        return false;
+    return urlKeys.some((key) => {
+        const raw = entry[key];
+        if (typeof raw !== "string")
+            return false;
+        try {
+            return !LOOPBACK_HOSTS.has(new URL(raw).hostname);
+        }
+        catch {
+            return false;
+        }
+    });
+}

package/dist/packs/omo.js

@@ -0,0 +1,149 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+const EXT_FILES = ["index.js", "discovery.md"];
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+function readOrNull(path) {
+    try {
+        if (!lstatSync(path).isFile())
+            return null;
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveOmoAgentDir(home, env) {
+    for (const name of ["OMO_CODING_AGENT_DIR", "SENPI_CODING_AGENT_DIR", "PI_CODING_AGENT_DIR"]) {
+        const v = env[name]?.trim();
+        if (v)
+            return resolve(v);
+    }
+    return join(home, ".omo", "agent");
+}
+export function resolveGajaeAgentDir(home, env) {
+    for (const name of ["GJC_CODING_AGENT_DIR", "PI_CODING_AGENT_DIR"]) {
+        const v = env[name]?.trim();
+        if (v)
+            return resolve(v);
+    }
+    const configDir = env.GJC_CONFIG_DIR?.trim() || env.PI_CONFIG_DIR?.trim() || ".gjc";
+    if (isAbsolute(configDir) || configDir.split(/[\\/]/).some(part => ["", ".", ".."].includes(part))) {
+        throw new Error("Use GJC_CODING_AGENT_DIR for an explicit Gajae profile path");
+    }
+    return join(home, configDir, "agent");
+}
+function isLoopbackUrl(raw) {
+    try {
+        const host = new URL(raw).hostname.replace(/^\[|\]$/g, "");
+        return host === "localhost" || host === "::1" || host.startsWith("127.");
+    }
+    catch {
+        return false;
+    }
+}
+function isRemoteGisul(server) {
+    if (!isObject(server))
+        return false;
+    if (typeof server.url === "string")
+        return !isLoopbackUrl(server.url);
+    const argv = [server.command, ...(Array.isArray(server.args) ? server.args : [])];
+    return argv.some(a => typeof a === "string" && a.includes("mcp-remote"));
+}
+function parseConfig(text) {
+    if (text === null)
+        return {};
+    try {
+        const v = JSON.parse(text);
+        return isObject(v) && (v.mcpServers === undefined || isObject(v.mcpServers)) ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createPiPack(spec) {
+    const extDir = (agentDir) => join(agentDir, "extensions", spec.extensionName);
+    return {
+        id: spec.id,
+        async detect({ home, env }) {
+            let agentDir;
+            try {
+                agentDir = spec.agentDir(home, env);
+            }
+            catch {
+                return { installed: false, evidence: [], remoteGisulRegistered: false };
+            }
+            const evidence = [agentDir, join(home, spec.installMarker)].filter(p => existsSync(p));
+            const cfg = parseConfig(readOrNull(join(agentDir, "mcp.json")));
+            const servers = isObject(cfg?.mcpServers) ? cfg.mcpServers : {};
+            return { installed: evidence.length > 0, evidence, remoteGisulRegistered: isRemoteGisul(servers.gisul) };
+        },
+        async plan(ctx) {
+            const plan = { files: [], commands: [], notes: [], conflicts: [] };
+            let agentDir;
+            try {
+                agentDir = spec.agentDir(ctx.home, ctx.env);
+            }
+            catch (e) {
+                plan.conflicts.push({ path: ctx.home, code: "agent_dir_unresolved", detail: e.message });
+                return plan;
+            }
+            const mcpPath = join(agentDir, "mcp.json");
+            const before = readOrNull(mcpPath);
+            const cfg = parseConfig(before);
+            if (!cfg) {
+                plan.conflicts.push({ path: mcpPath, code: "invalid_mcp_config", detail: "mcp.json is not a JSON object with an mcpServers map; left untouched" });
+                return plan;
+            }
+            const servers = { ...(isObject(cfg.mcpServers) ? cfg.mcpServers : {}) };
+            servers.gisool = { type: "http", url: `http://127.0.0.1:${ctx.port}/mcp`, headers: { Authorization: `Bearer ${ctx.token}` } };
+            if (ctx.disableRemote && isRemoteGisul(servers.gisul)) {
+                servers.gisul = { ...servers.gisul, enabled: false };
+                plan.notes.push("remote gisul entry set to enabled:false (original definition kept)");
+            }
+            const mcpAfter = JSON.stringify({ ...cfg, mcpServers: servers }, null, 2) + "\n";
+            plan.files.push({ path: mcpPath, before, after: mcpAfter, mode: 0o600 });
+            const dir = extDir(agentDir);
+            const source = join(ctx.packageRoot, "packs", spec.id, "extension");
+            const add = (path, after) => {
+                const f = { path, before: readOrNull(path), after, mode: 0o644 };
+                plan.files.push(f);
+            };
+            for (const name of EXT_FILES)
+                add(join(dir, name), readFileSync(join(source, name), "utf8"));
+            add(join(dir, "config.json"), JSON.stringify({ port: ctx.port }, null, 2) + "\n");
+            plan.notes.push(`extension forwarder installed at ${dir}; it reads the token from $GISOOL_HOME/token at load`);
+            return plan;
+        },
+        async doctorChecks({ home, env, port }) {
+            const checks = [];
+            let agentDir;
+            try {
+                agentDir = spec.agentDir(home, env);
+            }
+            catch (e) {
+                return [{ name: `${spec.id} agent dir`, ok: false, detail: e.message }];
+            }
+            const cfg = parseConfig(readOrNull(join(agentDir, "mcp.json")));
+            const entry = isObject(cfg?.mcpServers) ? cfg.mcpServers.gisool : undefined;
+            const want = `http://127.0.0.1:${port}/mcp`;
+            const url = isObject(entry) ? entry.url : undefined;
+            checks.push({ name: `${spec.id} mcp.json gisool`, ok: url === want, detail: url === want ? want : `expected ${want}, found ${String(url)}` });
+            const idx = join(extDir(agentDir), "index.js");
+            checks.push({ name: `${spec.id} extension forwarder`, ok: existsSync(idx), detail: idx });
+            const cfgPath = join(extDir(agentDir), "config.json");
+            let cfgPort;
+            try {
+                cfgPort = JSON.parse(readOrNull(cfgPath) ?? "{}").port;
+            }
+            catch { /* reported below */ }
+            checks.push({ name: `${spec.id} extension port`, ok: cfgPort === port, detail: cfgPort === port ? String(port) : `expected ${port}, found ${String(cfgPort)}` });
+            return checks;
+        },
+    };
+}
+export const omoPack = createPiPack({
+    id: "omo",
+    agentDir: resolveOmoAgentDir,
+    extensionName: "gisool",
+    installMarker: ".omo",
+});

package/dist/packs/openclaw.js

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+const CONFIG_NOTE = "Set plugins.entries.gisool.hooks.allowConversationAccess: true in the OpenClaw config (openclaw.json); without it before_agent_run is not delivered.";
+const TEMPLATES = new Set([".mcp.json", "openclaw.plugin.json", "gisool.json"]);
+function gisoolHome(env, home) {
+    return env.GISOOL_HOME || join(home, ".gisool");
+}
+function openclawConfigPath(env, home) {
+    return env.OPENCLAW_CONFIG_PATH || join(env.OPENCLAW_STATE_DIR || join(home, ".openclaw"), "openclaw.json");
+}
+function walk(dir) {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(join(dir, e.name)) : [join(dir, e.name)]));
+}
+function readOrNull(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function fill(node, vars) {
+    if (typeof node === "string")
+        return node in vars ? vars[node] : node;
+    if (Array.isArray(node))
+        return node.flatMap((n) => (typeof n === "string" && Array.isArray(vars[n]) ? vars[n] : [fill(n, vars)]));
+    if (node && typeof node === "object")
+        return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, fill(v, vars)]));
+    return node;
+}
+/** Tolerant read of an openclaw.json (JSON5-ish): strips comments and trailing commas, falls back to null. */
+function parseConfig(text) {
+    const stripped = text.replace(/("(?:[^"\\]|\\.)*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (_m, s) => s ?? "").replace(/,(\s*[}\]])/g, "$1");
+    try {
+        return JSON.parse(stripped);
+    }
+    catch {
+        return null;
+    }
+}
+const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const pluginEntries = (cfg) => (isRecord(cfg.plugins) && isRecord(cfg.plugins.entries) ? cfg.plugins.entries : undefined);
+function hasConversationAccess(text) {
+    const cfg = parseConfig(text);
+    if (isRecord(cfg))
+        return pluginEntries(cfg)?.gisool?.hooks?.allowConversationAccess === true;
+    return /allowConversationAccess["']?\s*:\s*true/.test(text);
+}
+export function bundleDir(env, home) {
+    return join(gisoolHome(env, home), "packs", "openclaw");
+}
+export const openclawPack = {
+    id: "openclaw",
+    async detect({ home, env }) {
+        const state = env.OPENCLAW_STATE_DIR || join(home, ".openclaw");
+        const evidence = [];
+        if (existsSync(state))
+            evidence.push(state);
+        if (existsSync(openclawConfigPath(env, home)))
+            evidence.push(openclawConfigPath(env, home));
+        const remote = [join(state, "gisul"), join(state, "plugins", "gisul"), join(state, "extensions", "gisul")].find(existsSync);
+        const cfgText = readOrNull(openclawConfigPath(env, home));
+        const cfg = cfgText ? parseConfig(cfgText) : null;
+        const entries = isRecord(cfg) ? pluginEntries(cfg) : undefined;
+        const remoteGisulRegistered = Boolean(remote) || Boolean(entries?.gisul || entries?.["gisul-openclaw"]);
+        if (remote)
+            evidence.push(remote);
+        return { installed: evidence.length > 0, evidence, remoteGisulRegistered };
+    },
+    async plan(ctx) {
+        const src = join(ctx.packageRoot, "packs", "openclaw");
+        const dest = bundleDir(ctx.env, ctx.home);
+        const vars = {
+            __COMMAND__: ctx.nodePath,
+            __ARGS__: [join(ctx.packageRoot, "dist", "cli", "main.js"), "mcp-stdio"],
+            __GISOOL_HOME__: gisoolHome(ctx.env, ctx.home),
+            __PORT__: ctx.port,
+        };
+        const files = walk(src)
+            .sort()
+            .map((abs) => {
+            const rel = relative(src, abs);
+            const raw = readFileSync(abs, "utf8");
+            const after = TEMPLATES.has(rel) ? JSON.stringify(fill(JSON.parse(raw), vars), null, 2) + "\n" : raw;
+            const path = join(dest, rel);
+            return { path, before: readOrNull(path), after, mode: statSync(abs).mode & 0o777 };
+        });
+        const notes = [
+            `Bundle files: ${files.map((f) => relative(dest, f.path)).join(", ")}`,
+            CONFIG_NOTE,
+            "Restart the OpenClaw Gateway after installing so the plugin and its hooks load.",
+        ];
+        const commands = [];
+        const install = ["openclaw", "plugins", "install", dest];
+        const uninstall = ["openclaw", "plugins", "uninstall", "gisool"];
+        if (ctx.env.GISOOL_NO_CLI)
+            notes.push(`GISOOL_NO_CLI set: run manually: ${install.join(" ")} (undo: ${uninstall.join(" ")})`);
+        else
+            commands.push({ argv: install, description: "Install the gisool capture plugin into OpenClaw (restart the OpenClaw Gateway afterwards)", undo: { argv: uninstall, description: "Uninstall the gisool OpenClaw plugin" } });
+        if (ctx.disableRemote)
+            notes.push("Remote gisul OpenClaw bundle is not removed automatically. To disable it run: openclaw plugins disable gisul-openclaw; to remove it run: openclaw plugins uninstall gisul-openclaw");
+        return { files, commands, notes, conflicts: [] };
+    },
+    async doctorChecks({ home, env }) {
+        const checks = [];
+        const bundle = bundleDir(env, home);
+        const bundled = existsSync(join(bundle, "openclaw.plugin.json"));
+        checks.push({ name: "openclaw bundle", ok: bundled, detail: bundled ? bundle : `bundle missing at ${bundle}; run gisool init` });
+        const cfgPath = openclawConfigPath(env, home);
+        const text = readOrNull(cfgPath);
+        if (text === null)
+            checks.push({ name: "allowConversationAccess", ok: false, detail: `allowConversationAccess missing: no OpenClaw config at ${cfgPath}` });
+        else if (hasConversationAccess(text))
+            checks.push({ name: "allowConversationAccess", ok: true, detail: cfgPath });
+        else
+            checks.push({ name: "allowConversationAccess", ok: false, detail: `allowConversationAccess missing: set plugins.entries.gisool.hooks.allowConversationAccess: true in ${cfgPath}` });
+        return checks;
+    },
+};

package/dist/packs/registry.js

@@ -0,0 +1,13 @@
+import { claudeCodePack } from "./claude-code.js";
+import { codexPack } from "./codex.js";
+import { cursorPack } from "./cursor.js";
+import { gajaePack } from "./gajae.js";
+import { geminiPack } from "./gemini.js";
+import { omoPack } from "./omo.js";
+import { openclawPack } from "./openclaw.js";
+/** Every runtime pack gisool ships, in the order init plans and doctor reports them. */
+export const PACKS = [claudeCodePack, codexPack, geminiPack, cursorPack, omoPack, gajaePack, openclawPack];
+export const PACK_IDS = PACKS.map((p) => p.id);
+export function getPack(id) {
+    return PACKS.find((p) => p.id === id);
+}

package/dist/search/fts.js

@@ -0,0 +1,61 @@
+import { isStopword, normalize, stem, words } from "./lexical.js";
+export const FTS_MIN_CHARS = 3;
+const length = (s) => Array.from(s).length;
+export function ftsTokens(query) {
+    const text = normalize(query);
+    if (length(text) < FTS_MIN_CHARS)
+        return [];
+    const tokens = new Set();
+    for (const word of words(text)) {
+        if (isStopword(word))
+            continue;
+        for (const t of [word, stem(word)])
+            if (length(t) >= FTS_MIN_CHARS)
+                tokens.add(t);
+    }
+    tokens.add(text);
+    return [...tokens];
+}
+export const ftsMatchExpression = (tokens) => tokens.map(t => `"${t.replace(/"/g, '""')}"`).join(" OR ");
+export class FtsIndex {
+    db;
+    insertStmt;
+    deleteStmt;
+    searchStmt;
+    texts = new Map();
+    constructor(db) {
+        this.db = db;
+        this.insertStmt = db.prepare("INSERT INTO skills_fts(uri, name, description, when_to_use, examples, aliases_ko, body_head) VALUES (?, ?, ?, ?, ?, ?, ?)");
+        this.deleteStmt = db.prepare("DELETE FROM skills_fts WHERE uri = ?");
+        // bm25 weights follow column order: uri, name, description, when_to_use, examples, aliases_ko, body_head.
+        this.searchStmt = db.prepare("SELECT uri, bm25(skills_fts, 0, 8, 2, 3, 5, 6, 1) AS score FROM skills_fts WHERE skills_fts MATCH ? ORDER BY score LIMIT ?");
+    }
+    clear() {
+        this.db.exec("DELETE FROM skills_fts");
+        this.texts.clear();
+    }
+    remove(uris) {
+        for (const uri of uris) {
+            this.deleteStmt.run(uri);
+            this.texts.delete(uri);
+        }
+    }
+    upsert(entries) {
+        for (const e of entries) {
+            this.deleteStmt.run(e.uri);
+            const fields = [e.name, e.description, e.whenToUse ?? "", e.examples.join("\n"), e.aliasesKo.join("\n"), e.bodyHead];
+            this.insertStmt.run(e.uri, ...fields);
+            this.texts.set(e.uri, normalize(fields.join(" ")));
+        }
+    }
+    search(query, limit = 50) {
+        const tokens = ftsTokens(query);
+        if (!tokens.length)
+            return [];
+        const rows = this.searchStmt.all(ftsMatchExpression(tokens), limit);
+        return rows.map((row, i) => {
+            const text = this.texts.get(row.uri) ?? "";
+            return { uri: row.uri, rank: i + 1, bm25: row.score, matched: tokens.filter(t => text.includes(t)) };
+        });
+    }
+}

package/dist/search/fusion.js

@@ -0,0 +1,50 @@
+export const RRF_K = 60;
+// Written by `node local/bench/search.mjs` from calibrate(); `--check` asserts it is current.
+export const DEFAULT_THRESHOLD = 0;
+const MAX_RRF = 2 / (RRF_K + 1);
+const round4 = (n) => Math.round(n * 1e4) / 1e4;
+/** Query terms (from lexical `terms()`) that a candidate's matched list covers; the dashboard shows the same count. */
+export function termCoverage(queryTerms, matched) {
+    const set = new Set(matched.map(m => m.normalize("NFKC").toLowerCase()));
+    return { hit: queryTerms.filter(t => set.has(t)).length, total: queryTerms.length };
+}
+/**
+ * Fuse both channels by reciprocal rank. Order uses raw RRF; the displayed score is the rank score scaled by the
+ * share of query terms the candidate matched, so a top rank on a weak match no longer reads as 1.00.
+ * Without `queryTerms` (or for a stopword-only query) coverage is 1 and the score stays rank-only.
+ */
+export function fuse(lexical, fts, queryTerms = []) {
+    const byUri = new Map();
+    const get = (uri) => {
+        let f = byUri.get(uri);
+        if (!f)
+            byUri.set(uri, f = { uri, score: 0, rrf: 0, anchor: 0, lexScore: 0, matched: [], coverage: 1 });
+        return f;
+    };
+    lexical.forEach((hit, i) => {
+        const f = get(hit.uri);
+        f.rrf += 1 / (RRF_K + i + 1);
+        f.anchor = hit.anchor;
+        f.lexScore = hit.score;
+        f.matched.push(...hit.matched);
+    });
+    for (const hit of fts) {
+        const f = get(hit.uri);
+        f.rrf += 1 / (RRF_K + hit.rank);
+        f.matched.push(...hit.matched);
+    }
+    const fused = [...byUri.values()];
+    for (const f of fused) {
+        f.matched = [...new Set(f.matched)];
+        const { hit, total } = termCoverage(queryTerms, f.matched);
+        f.coverage = total ? hit / total : 1;
+        // Normalize against the best possible RRF (rank 1 in both lists), scale by term coverage; anchors pin to 1.
+        f.score = f.anchor ? 1 : round4(Math.min(1, f.rrf / MAX_RRF) * f.coverage);
+    }
+    return fused.sort((a, b) => b.anchor - a.anchor || b.rrf - a.rrf || b.lexScore - a.lexScore || (a.uri < b.uri ? -1 : a.uri > b.uri ? 1 : 0));
+}
+/** Smallest threshold that makes every negative abstain: just above the best negative score, or 0 when none hit. */
+export function calibrate(negativeBestScores, margin = 0.01) {
+    const hits = negativeBestScores.filter(s => s > 0);
+    return hits.length ? round4(Math.min(1, Math.max(...hits) + margin)) : 0;
+}

package/dist/search/guidance.js

@@ -0,0 +1,7 @@
+export const SEARCH_TOOL_GUIDANCE = "Rewrite the user's task as a short English intent sentence using skill vocabulary (Korean is accepted). Do not pass skill bodies. Use mode=discovery.";
+export const ABSTAIN_HINTS = {
+    empty_query: "Describe the task as an intent sentence",
+    no_overlap: "No skill shares vocabulary with this query; rewrite it with skill vocabulary or continue without a skill",
+    below_threshold: "Matches are too weak; rephrase as a short intent sentence or continue without a skill",
+    explicit_only: "Only explicit-invocation skills matched; ask the user or search with mode=explicit",
+};

package/dist/search/index.js

@@ -0,0 +1,74 @@
+import { randomUUID } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { FtsIndex } from "./fts.js";
+import { DEFAULT_THRESHOLD, fuse } from "./fusion.js";
+import { ABSTAIN_HINTS } from "./guidance.js";
+import { buildLexical, normalize, terms } from "./lexical.js";
+export { DEFAULT_THRESHOLD, RRF_K, calibrate, fuse, termCoverage } from "./fusion.js";
+export { SEARCH_TOOL_GUIDANCE, ABSTAIN_HINTS } from "./guidance.js";
+export { normalize, terms } from "./lexical.js";
+export { ftsTokens } from "./fts.js";
+export function createSearchIndex(db) {
+    const entries = new Map();
+    const fts = new FtsIndex(db);
+    let lexical = buildLexical([]);
+    const thresholdStmt = db.prepare("SELECT value FROM meta WHERE key = 'search_threshold'");
+    const threshold = () => {
+        const row = thresholdStmt.get();
+        const value = row?.value == null ? NaN : Number(row.value);
+        return Number.isFinite(value) ? value : DEFAULT_THRESHOLD;
+    };
+    const transaction = (fn) => {
+        db.exec("BEGIN");
+        try {
+            fn();
+            db.exec("COMMIT");
+        }
+        catch (error) {
+            db.exec("ROLLBACK");
+            throw error;
+        }
+    };
+    return {
+        rebuild(list) {
+            transaction(() => { fts.clear(); fts.upsert(list); });
+            entries.clear();
+            for (const e of list)
+                entries.set(e.uri, e);
+            lexical = buildLexical([...entries.values()]);
+        },
+        apply(delta) {
+            const upserts = [...delta.added, ...delta.changed];
+            transaction(() => { fts.remove(delta.removed); fts.upsert(upserts); });
+            for (const uri of delta.removed)
+                entries.delete(uri);
+            for (const e of upserts)
+                entries.set(e.uri, e);
+            lexical = buildLexical([...entries.values()]);
+        },
+        search(query, opts) {
+            const started = performance.now();
+            const base = { traceId: randomUUID(), query, mode: opts.mode };
+            const done = (candidates, reason) => ({
+                ...base, candidates, ...(reason ? { abstained: { reason, hint: ABSTAIN_HINTS[reason] } } : {}),
+                elapsedMs: performance.now() - started,
+            });
+            const text = normalize(query ?? "");
+            if (!text)
+                return done([], "empty_query");
+            const fused = fuse(lexical.search(text), fts.search(text), terms(text)).filter(f => entries.has(f.uri));
+            if (!fused.length)
+                return done([], "no_overlap");
+            const allowed = opts.mode === "automatic" ? fused.filter(f => entries.get(f.uri).invocation === "automatic") : fused;
+            if (!allowed.length)
+                return done([], "explicit_only");
+            if (allowed[0].score < threshold())
+                return done([], "below_threshold");
+            const limit = Math.max(1, Math.floor(opts.limit));
+            return done(allowed.slice(0, limit).map((f, i) => {
+                const e = entries.get(f.uri);
+                return { uri: e.uri, name: e.name, description: e.description, score: f.score, rank: i + 1, invocation: e.invocation, digest: e.digest, matched: f.matched };
+            }));
+        },
+    };
+}