kibi-agent-core 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# kibi-agent-core
+
+## 0.1.0
+
+### Minor Changes
+
+- 5a06c03: Kibi's agent plugins now share one fast, consistent implementation for source-path classification, Kibi MCP tool recognition, and symbol-manifest indexing. Codex and ZCode now recognize production code outside `src/`, while Cursor reuses the same size-and-mtime-keyed scanner as Claude instead of parsing the full symbol manifest before an edit.
+
+  - Add `kibi-agent-core` as the common Node 18-compatible hook-helper package.
+  - Keep host adapters thin while preserving their host-specific event and state contracts.
+  - Replace Cursor's YAML parser dependency with the shared cached line scanner.
+
+## 0.0.0
+
+- Initial shared hook-helper package.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./kb-mcp-tools.js";
+export * from "./knowledge-index.js";
+export * from "./path-policy.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./kb-mcp-tools.js";
+export * from "./knowledge-index.js";
+export * from "./path-policy.js";

package/dist/kb-mcp-tools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical Kibi operation name for a host tool name. Hosts prefix MCP tools
+ * (`mcp__kibi__kb_check`, `mcp__plugin_<plugin>_kibi__kb_check`,
+ * `MCP:kb_check`, `kibi_kb_check`); an unprefixed `kb_check` passes through.
+ */
+export declare function canonicalKbToolName(toolName: string | undefined): string | undefined;
+export type KbMcpToolCall = {
+    toolName: string;
+    impactCheckRun: boolean;
+    sourceFiles: string[];
+};
+export type McpState = "observed" | "unknown";
+export type KibiInterface = "mcp" | "cli" | "setup";
+export declare function resolveKibiInterface(mcpState: McpState, workspaceTrusted: boolean): KibiInterface;
+export declare function extractKbMcpToolCall(toolName: string | undefined, toolInput: unknown): KbMcpToolCall | undefined;
+export declare function extractKbMcpToolName(toolName: string | undefined, toolInput: unknown): string | undefined;

package/dist/kb-mcp-tools.js

@@ -0,0 +1,164 @@
+// implements REQ-cursor-kibi-plugin-v1
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string") {
+            return value;
+        }
+    }
+    return undefined;
+}
+function readBoolean(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "boolean") {
+            return value;
+        }
+    }
+    return undefined;
+}
+function readStringArray(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (!Array.isArray(value)) {
+            continue;
+        }
+        return value.filter((item) => typeof item === "string" && item.length > 0);
+    }
+    return [];
+}
+function readRecord(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (isRecord(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Canonical Kibi operation name for a host tool name. Hosts prefix MCP tools
+ * (`mcp__kibi__kb_check`, `mcp__plugin_<plugin>_kibi__kb_check`,
+ * `MCP:kb_check`, `kibi_kb_check`); an unprefixed `kb_check` passes through.
+ */
+export function canonicalKbToolName(toolName) {
+    const trimmed = toolName?.trim() ?? "";
+    const lastSegment = trimmed.includes("__")
+        ? (trimmed.split("__").at(-1) ?? "")
+        : trimmed.replace(/^MCP:/i, "");
+    const operation = lastSegment.replace(/^kibi_/, "");
+    return operation.startsWith("kb_") ? operation : undefined;
+}
+export function resolveKibiInterface(mcpState, workspaceTrusted) {
+    if (mcpState === "observed") {
+        return "mcp";
+    }
+    return workspaceTrusted ? "cli" : "setup";
+}
+export function extractKbMcpToolCall(toolName, toolInput) {
+    let normalizedToolName = canonicalKbToolName(toolName);
+    if (isRecord(toolInput)) {
+        normalizedToolName ??= readString(toolInput, [
+            "toolName",
+            "tool_name",
+            "name",
+        ]);
+        const args = readRecord(toolInput, ["arguments", "args"]);
+        const payload = args ?? toolInput;
+        const includeImpactDiagnostics = readBoolean(payload, [
+            "includeImpactDiagnostics",
+            "include_impact_diagnostics",
+        ]);
+        const includeWorkingTreeDiff = readBoolean(payload, [
+            "includeWorkingTreeDiff",
+            "include_working_tree_diff",
+        ]);
+        const sourceFiles = readStringArray(payload, [
+            "sourceFiles",
+            "source_files",
+        ]);
+        if (normalizedToolName?.startsWith("kb_")) {
+            return {
+                toolName: normalizedToolName,
+                impactCheckRun: normalizedToolName === "kb_check" &&
+                    includeImpactDiagnostics === true &&
+                    includeWorkingTreeDiff === true &&
+                    sourceFiles.length > 0,
+                sourceFiles,
+            };
+        }
+        const nestedArgs = toolInput.arguments ?? toolInput.args;
+        if (isRecord(nestedArgs)) {
+            const nestedTool = readString(nestedArgs, [
+                "toolName",
+                "tool_name",
+                "name",
+            ]);
+            if (nestedTool?.startsWith("kb_")) {
+                return { toolName: nestedTool, impactCheckRun: false, sourceFiles: [] };
+            }
+        }
+    }
+    if (normalizedToolName?.startsWith("kb_")) {
+        return {
+            toolName: normalizedToolName,
+            impactCheckRun: false,
+            sourceFiles: [],
+        };
+    }
+    return undefined;
+}
+export function extractKbMcpToolName(toolName, toolInput) {
+    const toolCall = extractKbMcpToolCall(toolName, toolInput);
+    // rationale: the fallbacks below re-derive the same name from the same
+    // inputs, so dropping the toolCall shortcut is observationally equivalent.
+    // Stryker disable next-line ConditionalExpression, BlockStatement
+    if (toolCall) {
+        return toolCall.toolName;
+    }
+    // rationale: any tool name that trims to a kb_ prefix already produced a
+    // tool call above, so this branch only sees equivalent names.
+    // Stryker disable next-line MethodExpression
+    if (toolName) {
+        // rationale: any name that trims to a kb_ prefix already produced a tool
+        // call above, so this trim cannot change the returned name.
+        // Stryker disable MethodExpression
+        const normalized = toolName.trim();
+        if (normalized.startsWith("kb_")) {
+            return normalized;
+        }
+        // Stryker restore
+    }
+    if (!isRecord(toolInput)) {
+        return undefined;
+    }
+    // rationale: this alias list duplicates the one inside
+    // extractKbMcpToolCall, which already returned for every kb_ match.
+    // Stryker disable next-line StringLiteral
+    const directTool = readString(toolInput, ["toolName", "tool_name", "name"]);
+    if (directTool?.startsWith("kb_")) {
+        return directTool;
+    }
+    const nestedArgs = toolInput.arguments ?? toolInput.args;
+    if (isRecord(nestedArgs)) {
+        // rationale: this alias list duplicates the one inside
+        // extractKbMcpToolCall, which already returned for every kb_ match.
+        // Stryker disable next-line StringLiteral
+        // rationale: duplicate alias list; extractKbMcpToolCall already
+        // returned for every kb_ match.
+        // Stryker disable StringLiteral
+        const nestedTool = readString(nestedArgs, [
+            "toolName",
+            "tool_name",
+            "name",
+        ]);
+        // Stryker restore
+        if (nestedTool?.startsWith("kb_")) {
+            return nestedTool;
+        }
+    }
+    return undefined;
+}

package/dist/knowledge-index.d.ts

@@ -0,0 +1,50 @@
+export type KnowledgeIndexOptions = {
+    /** Legacy string links mean requirement ownership only in adapters that opt in. */
+    legacyLinksAsImplements?: boolean;
+    /** Lets multiple adapter indexes coexist in one host-owned cache directory. */
+    cacheFileName?: string;
+};
+export type IndexedSymbol = {
+    id: string;
+    title: string;
+    line?: number;
+    endLine?: number;
+    implements: string[];
+    coveredBy: string[];
+    executableFor: string[];
+};
+export type KnowledgeIndex = {
+    /** Workspace-relative source file -> symbols with at least one relationship. */
+    files: Record<string, IndexedSymbol[]>;
+    symbolCount: number;
+};
+type RawRecord = Record<string, unknown>;
+/**
+ * Scan the symbols manifest into raw records. Accepts both the canonical
+ * `symbols:` mapping and a bare top-level sequence.
+ */
+export declare function scanSymbolsManifest(text: string): RawRecord[];
+export type Coordinates = Record<string, {
+    line?: number;
+    endLine?: number;
+}>;
+/** Scan `coordinates:` -> `<symbol id>:` -> `sourceLine` / `sourceEndLine`. */
+export declare function scanSymbolCoordinates(text: string): Coordinates;
+/** Collapse raw manifest records and coordinates into the file-keyed index. */
+export declare function buildKnowledgeIndex(records: readonly RawRecord[], coordinates?: Coordinates, options?: KnowledgeIndexOptions): KnowledgeIndex;
+/**
+ * Load the index for a workspace, reusing the cache in `cacheDir` while both
+ * manifests keep their size and mtime.
+ */
+export declare function loadKnowledgeIndex(workspaceRoot: string, cacheDir?: string, options?: KnowledgeIndexOptions): KnowledgeIndex;
+export type EntitySummary = {
+    id: string;
+    title?: string;
+    status?: string;
+};
+/**
+ * Read an entity's title and status from its canonical authored document
+ * (`.kb/<lane>/<ID>.md`). Only the frontmatter head is read.
+ */
+export declare function readEntitySummary(workspaceRoot: string, entityId: string): EntitySummary;
+export {};

package/dist/knowledge-index.js

@@ -0,0 +1,388 @@
+// implements REQ-claude-code-kibi-plugin-v1
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * File-keyed view of the Kibi symbol manifest, built for hook latency.
+ *
+ * Hooks run before every read and edit, so they cannot afford a KB query
+ * (a CLI round trip costs seconds) or a full YAML parse of a large manifest.
+ * This module line-scans `.kb/symbols.yaml` and `.kb/symbol-coordinates.yaml`
+ * once, keeps only symbols that carry relationships, and caches the result as
+ * JSON keyed by both files' size and mtime. Every later hook pays one stat per
+ * file plus a JSON parse.
+ *
+ * The scanner understands the subset the Kibi writer emits (block mappings and
+ * sequences, quoted scalars, no line folding) plus hand-authored flow lists
+ * such as `links: [REQ-001]`. The manifest is a hint for progressive
+ * disclosure, not the source of truth: snippets always point at kb_query for
+ * the authoritative view.
+ */
+const SYMBOLS_MANIFEST = ".kb/symbols.yaml";
+const SYMBOL_COORDINATES = ".kb/symbol-coordinates.yaml";
+const INDEX_FORMAT = "kibi-agent-core.knowledge-index.v1";
+const CACHE_FILE = "knowledge-index.json";
+function unquote(raw) {
+    const value = raw.trim();
+    if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value.slice(1, -1);
+        }
+    }
+    if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+        return value.slice(1, -1).replaceAll("''", "'");
+    }
+    // Plain scalars may carry a trailing comment.
+    const comment = value.search(/\s#/);
+    return comment >= 0 ? value.slice(0, comment).trimEnd() : value;
+}
+function parseFlowList(raw) {
+    const value = raw.trim();
+    if (!value.startsWith("[") || !value.endsWith("]"))
+        return undefined;
+    const inner = value.slice(1, -1).trim();
+    if (inner.length === 0)
+        return [];
+    return inner
+        .split(",")
+        .map(unquote)
+        .filter((item) => item.length > 0);
+}
+const keyValue = /^([A-Za-z0-9_"'-][^:]*?):(?:\s+(.*))?$/;
+function parseScalarOrFlow(raw) {
+    if (raw === undefined || raw.trim().length === 0)
+        return undefined;
+    return parseFlowList(raw) ?? unquote(raw);
+}
+/**
+ * Scan the symbols manifest into raw records. Accepts both the canonical
+ * `symbols:` mapping and a bare top-level sequence.
+ */
+export function scanSymbolsManifest(text) {
+    const records = [];
+    let itemIndent;
+    let keyIndent = 0;
+    let current;
+    let listKey;
+    let listItem;
+    // Top-level section: symbols are the `symbols:` sequence or a bare root
+    // sequence; sequences under any other top-level key are ignored.
+    let section = "root";
+    for (const rawLine of text.split(/\r?\n/)) {
+        const content = rawLine.trim();
+        if (content.length === 0 || content.startsWith("#"))
+            continue;
+        const indent = rawLine.length - rawLine.trimStart().length;
+        const dash = /^(\s*)-(\s+)(.*)$/.exec(rawLine);
+        if (indent === 0 && !dash) {
+            const pair = keyValue.exec(content);
+            section =
+                pair?.[1] !== undefined && unquote(pair[1]) === "symbols"
+                    ? "symbols"
+                    : "other";
+            current = undefined;
+            itemIndent = undefined;
+            continue;
+        }
+        if (section === "other")
+            continue;
+        if (dash && (itemIndent === undefined || indent === itemIndent)) {
+            itemIndent = indent;
+            keyIndent = (dash[1]?.length ?? 0) + 1 + (dash[2]?.length ?? 1);
+            current = {};
+            records.push(current);
+            listKey = undefined;
+            listItem = undefined;
+            const pair = keyValue.exec(dash[3] ?? "");
+            if (pair?.[1] !== undefined) {
+                const value = parseScalarOrFlow(pair[2]);
+                if (value !== undefined)
+                    current[unquote(pair[1])] = value;
+                else
+                    listKey = unquote(pair[1]);
+            }
+            continue;
+        }
+        if (current === undefined || itemIndent === undefined)
+            continue;
+        if (indent <= itemIndent)
+            continue;
+        if (dash) {
+            if (listKey === undefined)
+                continue;
+            const list = Array.isArray(current[listKey])
+                ? current[listKey]
+                : [];
+            current[listKey] = list;
+            const pair = keyValue.exec(dash[3] ?? "");
+            if (pair?.[1] !== undefined && pair[2] !== undefined) {
+                listItem = { [unquote(pair[1])]: unquote(pair[2]) };
+                list.push(listItem);
+            }
+            else {
+                listItem = undefined;
+                list.push(unquote(dash[3] ?? ""));
+            }
+            continue;
+        }
+        const pair = keyValue.exec(content);
+        if (pair?.[1] === undefined)
+            continue;
+        const key = unquote(pair[1]);
+        if (indent === keyIndent) {
+            listItem = undefined;
+            const value = parseScalarOrFlow(pair[2]);
+            if (value === undefined) {
+                listKey = key;
+            }
+            else {
+                current[key] = value;
+                listKey = undefined;
+            }
+        }
+        else if (listItem !== undefined && pair[2] !== undefined) {
+            listItem[key] = unquote(pair[2]);
+        }
+    }
+    return records;
+}
+/** Scan `coordinates:` -> `<symbol id>:` -> `sourceLine` / `sourceEndLine`. */
+export function scanSymbolCoordinates(text) {
+    const coordinates = {};
+    let inCoordinates = false;
+    let idIndent;
+    let currentId;
+    for (const rawLine of text.split(/\r?\n/)) {
+        const content = rawLine.trim();
+        if (content.length === 0 || content.startsWith("#"))
+            continue;
+        const indent = rawLine.length - rawLine.trimStart().length;
+        const pair = keyValue.exec(content);
+        if (pair?.[1] === undefined)
+            continue;
+        const key = unquote(pair[1]);
+        if (indent === 0) {
+            inCoordinates = key === "coordinates";
+            idIndent = undefined;
+            currentId = undefined;
+            continue;
+        }
+        if (!inCoordinates)
+            continue;
+        if (idIndent === undefined || indent === idIndent) {
+            idIndent = indent;
+            currentId = key;
+            coordinates[currentId] ??= {};
+            continue;
+        }
+        if (currentId === undefined || indent < idIndent)
+            continue;
+        const entry = coordinates[currentId] ?? {};
+        const numeric = Number.parseInt(unquote(pair[2] ?? ""), 10);
+        if (!Number.isFinite(numeric))
+            continue;
+        if (key === "sourceLine")
+            entry.line = numeric;
+        if (key === "sourceEndLine")
+            entry.endLine = numeric;
+        coordinates[currentId] = entry;
+    }
+    return coordinates;
+}
+function toPositiveInt(value) {
+    const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+function pushUnique(list, value) {
+    if (!list.includes(value))
+        list.push(value);
+}
+/** Collapse raw manifest records and coordinates into the file-keyed index. */
+export function buildKnowledgeIndex(records, coordinates = {}, options = {}) {
+    const files = {};
+    let symbolCount = 0;
+    for (const record of records) {
+        const id = typeof record.id === "string" ? record.id : undefined;
+        const sourceFile = typeof record.sourceFile === "string"
+            ? record.sourceFile.replaceAll("\\", "/").replace(/^\.\//, "")
+            : undefined;
+        if (!id || !sourceFile)
+            continue;
+        symbolCount += 1;
+        const symbol = {
+            id,
+            title: typeof record.title === "string" ? record.title : id,
+            implements: [],
+            coveredBy: [],
+            executableFor: [],
+        };
+        const relationships = [];
+        if (options.legacyLinksAsImplements !== false) {
+            let links = [];
+            if (typeof record.links === "string")
+                links = [record.links];
+            else if (Array.isArray(record.links))
+                links = record.links;
+            for (const link of links) {
+                if (typeof link === "string") {
+                    relationships.push({ type: "implements", target: link });
+                }
+                else if (link !== null && typeof link === "object") {
+                    const typed = link;
+                    if (typeof typed.type === "string" &&
+                        typeof typed.target === "string") {
+                        relationships.push({ type: typed.type, target: typed.target });
+                    }
+                }
+            }
+        }
+        for (const relation of Array.isArray(record.relationships)
+            ? record.relationships
+            : []) {
+            if (relation === null || typeof relation !== "object")
+                continue;
+            const typed = relation;
+            if (typeof typed.type === "string" && typeof typed.target === "string")
+                relationships.push({ type: typed.type, target: typed.target });
+        }
+        for (const { type, target } of relationships) {
+            if (type === "implements")
+                pushUnique(symbol.implements, target);
+            else if (type === "covered_by")
+                pushUnique(symbol.coveredBy, target);
+            else if (type === "executable_for")
+                pushUnique(symbol.executableFor, target);
+        }
+        if (symbol.implements.length +
+            symbol.coveredBy.length +
+            symbol.executableFor.length ===
+            0) {
+            continue;
+        }
+        const line = toPositiveInt(record.sourceLine) ?? coordinates[id]?.line ?? undefined;
+        const endLine = toPositiveInt(record.sourceEndLine) ??
+            coordinates[id]?.endLine ??
+            undefined;
+        if (line !== undefined)
+            symbol.line = line;
+        if (endLine !== undefined)
+            symbol.endLine = endLine;
+        const bucket = files[sourceFile] ?? [];
+        bucket.push(symbol);
+        files[sourceFile] = bucket;
+    }
+    return { files, symbolCount };
+}
+function fileSignature(filePath) {
+    try {
+        const stats = fs.statSync(filePath);
+        return `${stats.size}:${stats.mtimeMs}`;
+    }
+    catch {
+        return "missing";
+    }
+}
+function readText(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCacheAtomically(cachePath, payload) {
+    try {
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+        const temporary = `${cachePath}.${process.pid}.${randomUUID()}.tmp`;
+        fs.writeFileSync(temporary, payload);
+        fs.renameSync(temporary, cachePath);
+    }
+    catch {
+        // The cache is an optimization; a failed write only costs the next hook a rescan.
+    }
+}
+/**
+ * Load the index for a workspace, reusing the cache in `cacheDir` while both
+ * manifests keep their size and mtime.
+ */
+export function loadKnowledgeIndex(workspaceRoot, cacheDir, options = {}) {
+    const symbolsPath = path.join(workspaceRoot, SYMBOLS_MANIFEST);
+    const coordinatesPath = path.join(workspaceRoot, SYMBOL_COORDINATES);
+    const legacyMode = options.legacyLinksAsImplements === false ? "typed" : "legacy";
+    const signature = `${INDEX_FORMAT}|${legacyMode}|${fileSignature(symbolsPath)}|${fileSignature(coordinatesPath)}`;
+    const cachePath = cacheDir
+        ? path.join(cacheDir, options.cacheFileName ?? CACHE_FILE)
+        : undefined;
+    if (cachePath) {
+        const cached = readText(cachePath);
+        if (cached !== undefined) {
+            try {
+                const parsed = JSON.parse(cached);
+                if (parsed.signature === signature && parsed.index)
+                    return parsed.index;
+            }
+            catch {
+                // Corrupt cache: rebuild below.
+            }
+        }
+    }
+    const symbolsText = readText(symbolsPath);
+    const index = symbolsText === undefined
+        ? { files: {}, symbolCount: 0 }
+        : buildKnowledgeIndex(scanSymbolsManifest(symbolsText), scanSymbolCoordinates(readText(coordinatesPath) ?? ""), options);
+    if (cachePath) {
+        writeCacheAtomically(cachePath, JSON.stringify({ signature, index }));
+    }
+    return index;
+}
+const ENTITY_LANES = [
+    ["REQ-", "requirements"],
+    ["SCEN-", "scenarios"],
+    ["TEST-", "tests"],
+    ["ADR-", "adr"],
+    ["FACT-", "facts"],
+    ["FLAG-", "flags"],
+    ["EVT-", "events"],
+];
+const SAFE_ENTITY_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Read an entity's title and status from its canonical authored document
+ * (`.kb/<lane>/<ID>.md`). Only the frontmatter head is read.
+ */
+export function readEntitySummary(workspaceRoot, entityId) {
+    const lane = ENTITY_LANES.find(([prefix]) => entityId.startsWith(prefix));
+    if (!lane || !SAFE_ENTITY_ID.test(entityId))
+        return { id: entityId };
+    let head;
+    try {
+        const descriptor = fs.openSync(path.join(workspaceRoot, ".kb", lane[1], `${entityId}.md`), "r");
+        try {
+            const buffer = Buffer.alloc(4096);
+            const bytes = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
+            head = buffer.subarray(0, bytes).toString("utf8");
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+    }
+    catch {
+        return { id: entityId };
+    }
+    const lines = head.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return { id: entityId };
+    const summary = { id: entityId };
+    for (const line of lines.slice(1)) {
+        if (line.trim() === "---")
+            break;
+        const match = /^(title|status):\s*(.*)$/.exec(line);
+        if (match?.[1] === "title" && match[2])
+            summary.title = unquote(match[2]);
+        if (match?.[1] === "status" && match[2])
+            summary.status = unquote(match[2]);
+    }
+    return summary;
+}

package/dist/path-policy.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What a workspace path means for Kibi guidance.
+ *
+ * - `source`: production code whose behavior requirements may own.
+ * - `test`: test code (owned through TEST entities / executable_for).
+ * - `kb`: Kibi-managed knowledge under `.kb/`.
+ * - `other`: docs, config, generated output, dependencies — no snippets.
+ *
+ * Source detection deliberately does not require a `src/` segment: `lib/`,
+ * `app/`, and root-level packages are source too.
+ */
+export type PathKind = "source" | "test" | "kb" | "other";
+export type WorkspacePath = {
+    /** Path relative to the workspace root, forward slashes. */
+    relative: string;
+    absolute: string;
+};
+export type CanonicalWorkspacePath = {
+    workspaceRelative: string;
+    absolute: string;
+};
+export declare function normalizeWorkspacePath(candidate: string): string;
+export declare function extractExplicitPathFields(input: unknown): string[];
+export declare function canonicalizeWorkspacePath(workspaceRoot: string, options: {
+    eventCwd?: string | undefined;
+    base?: string | undefined;
+    rawPath: string;
+}): CanonicalWorkspacePath | undefined;
+/**
+ * Resolve a tool-call path against the event cwd and express it relative to
+ * the Kibi workspace root. Paths outside the workspace return undefined.
+ */
+export declare function toWorkspacePath(workspaceRoot: string, rawPath: string, eventCwd?: string): WorkspacePath | undefined;
+export declare function classifyPath(relativePath: string): PathKind;
+export declare function isKbPath(candidate: string): boolean;
+export declare function isRootKbPath(candidate: string): boolean;
+export declare function isMeaningfulTrackedPath(candidate: string): boolean;
+export declare function isSourceImpactRelevantPath(candidate: string): boolean;
+export declare function isDocumentationTrackedPath(candidate: string): boolean;

package/dist/path-policy.js

@@ -0,0 +1,221 @@
+// implements REQ-claude-code-kibi-plugin-v1
+import path from "node:path";
+const codeExtensions = new Set([
+    ".c",
+    ".cc",
+    ".cjs",
+    ".cpp",
+    ".cs",
+    ".css",
+    ".go",
+    ".h",
+    ".hpp",
+    ".html",
+    ".java",
+    ".js",
+    ".jsx",
+    ".kt",
+    ".lua",
+    ".mjs",
+    ".mts",
+    ".cts",
+    ".php",
+    ".pl",
+    ".py",
+    ".rb",
+    ".rs",
+    ".scala",
+    ".sh",
+    ".swift",
+    ".ts",
+    ".tsx",
+    ".vue",
+    ".svelte",
+]);
+/** Directories whose contents are generated, vendored, or tool state. */
+const ignoredSegments = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    "vendor",
+    "target",
+    ".git",
+    ".next",
+    ".turbo",
+    ".cache",
+    "__pycache__",
+]);
+const testSegments = new Set([
+    "test",
+    "tests",
+    "__tests__",
+    "spec",
+    "specs",
+    "e2e",
+    "__mocks__",
+    "fixtures",
+]);
+const testBasename = /(\.|_)(test|spec|e2e)\.[^.]+$|^test_[^/]+\.py$/;
+const documentationExtensions = new Set([".md", ".mdx", ".rst", ".txt"]);
+const documentationSegments = new Set(["docs", "documentation"]);
+const canonicalKbKnowledgeLanes = new Set([
+    "requirements",
+    "scenarios",
+    "tests",
+    "facts",
+    "adr",
+    "flags",
+    "events",
+]);
+const canonicalKbKnowledgeFiles = new Set([
+    "symbols.yaml",
+    "symbol-coordinates.yaml",
+]);
+const explicitPathKeys = new Set([
+    "absolute_path",
+    "file",
+    "file_path",
+    "filepath",
+    "new_path",
+    "old_path",
+    "path",
+    "paths",
+    "relative_path",
+    "target_path",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function normalizeWorkspacePath(candidate) {
+    return candidate.trim().replaceAll("\\", "/");
+}
+function pathSegments(candidate) {
+    return normalizeWorkspacePath(candidate).split("/").filter(Boolean);
+}
+function collectPathValues(value, output) {
+    if (typeof value === "string") {
+        const normalized = normalizeWorkspacePath(value);
+        if (normalized.length > 0)
+            output.push(normalized);
+        return;
+    }
+    if (!Array.isArray(value))
+        return;
+    for (const item of value)
+        collectPathValues(item, output);
+}
+function visitExplicitPathFields(value, output) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            visitExplicitPathFields(item, output);
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (explicitPathKeys.has(key.toLowerCase()))
+            collectPathValues(child, output);
+        visitExplicitPathFields(child, output);
+    }
+}
+export function extractExplicitPathFields(input) {
+    const paths = [];
+    visitExplicitPathFields(input, paths);
+    return [...new Set(paths)];
+}
+export function canonicalizeWorkspacePath(workspaceRoot, options) {
+    const trimmed = normalizeWorkspacePath(options.rawPath);
+    if (trimmed.length === 0)
+        return undefined;
+    const base = options.base ?? options.eventCwd ?? workspaceRoot;
+    const absolute = path.isAbsolute(trimmed)
+        ? path.resolve(trimmed)
+        : path.resolve(base, trimmed);
+    const workspaceRelative = path
+        .relative(workspaceRoot, absolute)
+        .replaceAll("\\", "/");
+    if (workspaceRelative.length === 0 ||
+        workspaceRelative === ".." ||
+        workspaceRelative.startsWith("../") ||
+        path.isAbsolute(workspaceRelative)) {
+        return undefined;
+    }
+    return { workspaceRelative, absolute };
+}
+/**
+ * Resolve a tool-call path against the event cwd and express it relative to
+ * the Kibi workspace root. Paths outside the workspace return undefined.
+ */
+export function toWorkspacePath(workspaceRoot, rawPath, eventCwd) {
+    const canonical = canonicalizeWorkspacePath(workspaceRoot, {
+        rawPath,
+        eventCwd,
+    });
+    return canonical
+        ? { relative: canonical.workspaceRelative, absolute: canonical.absolute }
+        : undefined;
+}
+export function classifyPath(relativePath) {
+    const segments = pathSegments(relativePath);
+    if (segments[0] === ".kb")
+        return "kb";
+    if (segments.some((segment) => ignoredSegments.has(segment)))
+        return "other";
+    if (segments.some((segment) => documentationSegments.has(segment))) {
+        return "other";
+    }
+    const basename = segments.at(-1) ?? "";
+    const extension = path.extname(basename).toLowerCase();
+    if (!codeExtensions.has(extension))
+        return "other";
+    if (testBasename.test(basename) ||
+        segments.slice(0, -1).some((segment) => testSegments.has(segment))) {
+        return "test";
+    }
+    return "source";
+}
+export function isKbPath(candidate) {
+    return pathSegments(candidate).includes(".kb");
+}
+export function isRootKbPath(candidate) {
+    return pathSegments(candidate)[0] === ".kb";
+}
+function isCanonicalKbKnowledgePath(segments) {
+    const kbIndex = segments.indexOf(".kb");
+    if (kbIndex < 0)
+        return false;
+    const lane = segments[kbIndex + 1];
+    return (lane !== undefined &&
+        (canonicalKbKnowledgeFiles.has(lane) || canonicalKbKnowledgeLanes.has(lane)));
+}
+export function isMeaningfulTrackedPath(candidate) {
+    const segments = pathSegments(candidate);
+    if (segments.some((segment) => ignoredSegments.has(segment)))
+        return false;
+    if (segments.includes(".kb"))
+        return isCanonicalKbKnowledgePath(segments);
+    const basename = segments.at(-1) ?? "";
+    const extension = path.extname(basename).toLowerCase();
+    if (basename === "README.md")
+        return true;
+    if (segments.some((segment) => documentationSegments.has(segment))) {
+        return documentationExtensions.has(extension);
+    }
+    if (testBasename.test(basename) ||
+        segments.slice(0, -1).some((segment) => testSegments.has(segment))) {
+        return (codeExtensions.has(extension) || documentationExtensions.has(extension));
+    }
+    return codeExtensions.has(extension);
+}
+export function isSourceImpactRelevantPath(candidate) {
+    return classifyPath(normalizeWorkspacePath(candidate)) === "source";
+}
+export function isDocumentationTrackedPath(candidate) {
+    const segments = pathSegments(candidate);
+    const basename = segments.at(-1) ?? "";
+    return (basename === "README.md" ||
+        segments.some((segment) => documentationSegments.has(segment)) ||
+        documentationExtensions.has(path.extname(basename).toLowerCase()));
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "kibi-agent-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Shared low-latency hook helpers for Kibi agent adapters",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./kb-mcp-tools": {
+      "types": "./dist/kb-mcp-tools.d.ts",
+      "default": "./dist/kb-mcp-tools.js"
+    },
+    "./knowledge-index": {
+      "types": "./dist/knowledge-index.d.ts",
+      "default": "./dist/knowledge-index.js"
+    },
+    "./path-policy": {
+      "types": "./dist/path-policy.d.ts",
+      "default": "./dist/path-policy.js"
+    }
+  },
+  "files": ["dist", "CHANGELOG.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build && node ../../scripts/verify-package-contract.mjs kibi-agent-core"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "AGPL-3.0-or-later",
+  "author": "Piotr Franczyk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Looted/kibi.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.8",
+    "semver": "^7.8.5",
+    "typescript": "^5.7.0",
+    "yaml": "^2.9.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.