kibi-agent-core 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # kibi-agent-core
 
+## 0.11.1
+
+### Patch Changes
+
+- The telemetry status carries the channel in effect and where it comes from (`channel`, `channelSource`), and `telemetryChannel` returns both.
+
+- Edit snippets say what the lead requirement must keep true as the claims its facts model, in words with their operator and members (for example "REQ-GREET must keep true: The greet function must not call console.log."), or as the requirement's own statement, instead of listing internal fact IDs and subject keys. A requirement title that an older Kibi cut at a dot inside a name is shown whole.
+
+- f9ec786: Usage telemetry events now carry a `channel`: `release` for an installed Kibi package, `source` when Kibi runs from a checkout of its own repository, or the value of `KIBI_TELEMETRY_CHANNEL` when a harness sets one (for example `agent-test`). Development and test runs can then be filtered out of real usage. Nothing else about what is sent changes.
+
 ## 0.11.0
 
 ### Minor Changes

package/dist/knowledge-index.d.ts

@@ -82,6 +82,21 @@ export type EntitySummary = {
      * with canonical relationship-shard records whose `from` is this entity.
      */
     links?: EntityLink[];
+    /** Requirement prose: `semantic_text`, else the body's first paragraph. */
+    statement?: string;
+    /** The claim a fact models, from its typed front matter fields. */
+    claim?: FactClaim;
+};
+/** A fact's typed fields, as authored; absent fields are left out. */
+export type FactClaim = {
+    factKind?: string;
+    subjectKey?: string;
+    propertyKey?: string;
+    operator?: string;
+    /** `value_set` members, or the one scalar value. */
+    values?: string[];
+    unit?: string;
+    claimText?: string;
 };
 /**
  * Read an entity's title, status and outgoing links. Title and status come

package/dist/knowledge-index.js

@@ -636,6 +636,62 @@ const ENTITY_LANES = [
     ["EVT-", "events"],
 ];
 const SAFE_ENTITY_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Front matter scalars a summary keeps, by field name. */
+const SUMMARY_SCALARS = {
+    semantic_text: "statement",
+    fact_kind: "factKind",
+    subject_key: "subjectKey",
+    property_key: "propertyKey",
+    operator: "operator",
+    unit: "unit",
+    claim_text: "claimText",
+};
+const SCALAR_VALUE_FIELDS = new Set([
+    "value_string",
+    "value_int",
+    "value_number",
+    "value_bool",
+]);
+/**
+ * A front matter scalar starting at `lines[index]` with `raw` after its key:
+ * a plain or quoted value with its indented continuation lines, or a block
+ * scalar (`>-`, `|`). Returns the value and the last line it used.
+ */
+function readScalar(lines, index, raw) {
+    const block = /^[>|][+-]?$/.test(raw.trim());
+    const parts = block ? [] : [raw.trim()];
+    let last = index;
+    while (last + 1 < lines.length) {
+        const next = lines[last + 1] ?? "";
+        if (next.trim() === "---" || !/^\s+\S/.test(next))
+            break;
+        if (!block && /^\s+-\s/.test(next))
+            break;
+        parts.push(next.trim());
+        last += 1;
+    }
+    const joined = parts.join(" ").trim();
+    return { value: block ? joined : unquote(joined), last };
+}
+/** The first prose paragraph of a Markdown body, headings skipped. */
+function firstParagraph(lines) {
+    const paragraph = [];
+    for (const line of lines) {
+        const text = line.trim();
+        if (text === "") {
+            if (paragraph.length > 0)
+                break;
+            continue;
+        }
+        if (/^#{1,6}\s/.test(text)) {
+            if (paragraph.length > 0)
+                break;
+            continue;
+        }
+        paragraph.push(text);
+    }
+    return paragraph.length > 0 ? paragraph.join(" ") : undefined;
+}
 const MAX_SUMMARY_LINKS = 24;
 const RELATIONSHIPS_DIR = ".kb/relationships";
 /**
@@ -713,16 +769,53 @@ export function readEntitySummary(workspaceRoot, entityId) {
         return { id: entityId };
     const summary = { id: entityId };
     const authored = [];
+    const claim = {};
+    const values = [];
     let inLinks = false;
+    let inValueSet = false;
     let inOrigin = false;
     let originKind;
     let closed = false;
+    let bodyStart = lines.length;
     let pending;
-    for (const line of lines.slice(1)) {
+    for (let index = 1; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
         if (line.trim() === "---") {
             closed = true;
+            bodyStart = index + 1;
             break;
         }
+        const scalar = /^([a-z_]+):\s*(.*)$/.exec(line);
+        const scalarField = scalar ? SUMMARY_SCALARS[scalar[1] ?? ""] : undefined;
+        if (scalar && scalarField && scalar[2]) {
+            const { value, last } = readScalar(lines, index, scalar[2]);
+            if (value !== "") {
+                if (scalarField === "statement")
+                    summary.statement = value;
+                else if (scalarField !== "values")
+                    claim[scalarField] = value;
+            }
+            index = last;
+            flushLink(authored, pending);
+            pending = undefined;
+            inLinks = false;
+            inValueSet = false;
+            continue;
+        }
+        if (scalar && SCALAR_VALUE_FIELDS.has(scalar[1] ?? "") && scalar[2]) {
+            values.push(unquote(scalar[2]));
+        }
+        const flowSet = /^value_set:\s*\[(.*)\]\s*$/.exec(line);
+        if (flowSet?.[1]?.trim()) {
+            values.push(...flowSet[1].split(",").map((member) => unquote(member)));
+        }
+        if (/^\S/.test(line))
+            inValueSet = /^value_set:\s*$/.test(line);
+        else if (inValueSet) {
+            const member = /^\s*-\s*(.+)$/.exec(line);
+            if (member)
+                values.push(unquote(member[1] ?? ""));
+        }
         // implements REQ-kb-decision-firmness-from-origin
         const flowOrigin = /^origin:\s*\{.*\bkind:\s*["']?([a-z]+)/.exec(line);
         if (flowOrigin)
@@ -791,5 +884,14 @@ export function readEntitySummary(workspaceRoot, entityId) {
     }
     if (links.length > 0)
         summary.links = links;
+    if (values.length > 0)
+        claim.values = values;
+    if (Object.keys(claim).length > 0)
+        summary.claim = claim;
+    if (summary.statement === undefined && lane[1] === "requirements" && closed) {
+        const paragraph = firstParagraph(lines.slice(bodyStart));
+        if (paragraph)
+            summary.statement = paragraph;
+    }
     return summary;
 }

package/dist/snippets.d.ts

@@ -44,10 +44,20 @@ export declare function unreadableManifestNote(relativePath: string): string;
 /** Link types through which a requirement is grounded in semantic facts. */
 export declare const GROUNDING_LINK_TYPES: readonly string[];
 /**
- * What a requirement says must stay true (its linked facts) and the decision
- * behind it (a linked ADR), read from its frontmatter links and
- * relationship-shard records. A retired requirement is not current policy, so
- * its grounding is not presented as something to keep true.
+ * A property fact as a sentence naming its operator and members ("The greet
+ * function must not call console.log"); a predicate or rule fact as the
+ * claim text it models. Undefined for a subject fact and for a fact without
+ * readable fields.
+ */
+export declare function factClaimSentence(summary: EntitySummary): string | undefined;
+/**
+ * What a requirement says must stay true and the decision behind it (a
+ * linked ADR), read from its frontmatter links and relationship-shard
+ * records. Each linked fact is shown as the claim it models, with its
+ * operator and members (a fact without typed fields by its title); without
+ * one the requirement's own statement is shown. Fact IDs are internal and
+ * never shown. A retired requirement is not current policy, so its grounding
+ * is not presented as something to keep true.
  */
 export declare function requirementGroundingLines(requirementId: string, summarize: Summarize, options?: {
     maxFacts?: number;

package/dist/snippets.js

@@ -18,6 +18,7 @@ const MAX_SYMBOLS_PER_REQUIREMENT = 3;
 const MAX_TESTS = 3;
 const MAX_TITLE = 80;
 const MAX_GROUNDING = 2;
+const MAX_CLAIM = 160;
 /** Files larger than this are not scanned to locate an edit. */
 const MAX_FOCUS_SCAN_BYTES = 2 * 1024 * 1024;
 // implements REQ-claude-code-kibi-plugin-v1, REQ-cursor-kibi-plugin-v1
@@ -118,10 +119,25 @@ export function describeEntity(summary) {
             : " [exploratory]"
         : "";
     const notable = `${retired}${firmness}`;
-    return summary.title
-        ? `${summary.id}${notable}: ${truncate(summary.title, MAX_TITLE)}`
+    const title = displayTitle(summary);
+    return title
+        ? `${summary.id}${notable}: ${truncate(title, MAX_TITLE)}`
         : `${summary.id}${notable}`;
 }
+/**
+ * The title, completed from the statement when an older title was cut at a
+ * dot inside a name ("...call console" for "...call console.log").
+ */
+function displayTitle(summary) {
+    const { title, statement } = summary;
+    if (!title || !statement?.startsWith(title))
+        return title;
+    const rest = statement.slice(title.length);
+    if (!/^\.\S/.test(rest))
+        return title;
+    const end = rest.search(/[.!?](?:\s|$)/);
+    return end < 0 ? statement : statement.slice(0, title.length + end);
+}
 function jsonString(value) {
     return JSON.stringify(value);
 }
@@ -178,12 +194,94 @@ export const GROUNDING_LINK_TYPES = [
     "requires_predicate",
     "requires_rule",
 ];
+/** Set-valued properties whose claim reads as a verb on the members. */
+const PROPERTY_VERBS = {
+    calls: "call",
+    imports: "import",
+    reads: "read",
+    uses: "use",
+    throws: "throw",
+};
+/** How a scalar or set property is constrained, by fact operator. */
+const OPERATOR_PHRASES = {
+    eq: "must be",
+    neq: "must not be",
+    lt: "must be less than",
+    lte: "must be at most",
+    gt: "must be greater than",
+    gte: "must be at least",
+    matches: "must match",
+    includes: "must include",
+    subset_of: "must be within",
+    excludes: "must not include",
+};
+function joinMembers(values, conjunction) {
+    if (values.length <= 1)
+        return values[0] ?? "";
+    return `${values.slice(0, -1).join(", ")} ${conjunction} ${values.at(-1)}`;
+}
+const MODAL = /^(.{1,100}?)\s+(?:must|may|can|cannot|should|shall|will|never)\b/i;
+/** The claim's own subject words, before its modal verb, else the key's. */
+function subjectPhrase(claim) {
+    const spoken = MODAL.exec(claim.claimText ?? "")?.[1];
+    if (spoken)
+        return spoken;
+    return claim.subjectKey?.replace(/[._]+/g, " ").trim() || undefined;
+}
+// implements REQ-agent-core-edit-snippets
+/**
+ * A property fact as a sentence naming its operator and members ("The greet
+ * function must not call console.log"); a predicate or rule fact as the
+ * claim text it models. Undefined for a subject fact and for a fact without
+ * readable fields.
+ */
+export function factClaimSentence(summary) {
+    const claim = summary.claim;
+    if (!claim || claim.factKind === "subject")
+        return undefined;
+    const values = claim.values ?? [];
+    if (claim.propertyKey && claim.operator && values.length > 0) {
+        const subject = subjectPhrase(claim);
+        if (!subject)
+            return claim.claimText;
+        const verb = PROPERTY_VERBS[claim.propertyKey];
+        const verbal = verb
+            ? {
+                excludes: `must not ${verb} ${joinMembers(values, "or")}`,
+                includes: `must ${verb} ${joinMembers(values, "and")}`,
+                subset_of: `may ${verb} only ${joinMembers(values, "or")}`,
+                eq: `must ${verb} exactly ${joinMembers(values, "and")}`,
+            }[claim.operator]
+            : undefined;
+        if (verbal)
+            return `${subject} ${verbal}`;
+        const phrase = OPERATOR_PHRASES[claim.operator];
+        if (phrase) {
+            const property = claim.propertyKey.replace(/_+/g, " ");
+            const unit = claim.unit ? ` ${claim.unit}` : "";
+            return `${subject}: ${property} ${phrase} ${values.join(", ")}${unit}`;
+        }
+    }
+    return claim.claimText;
+}
+/** A fact's claim sentence, else its authored title; a subject fact adds nothing. */
+function groundingText(summary) {
+    if (summary.claim?.factKind === "subject")
+        return undefined;
+    return factClaimSentence(summary) ?? summary.title;
+}
+function withoutClosingStop(text) {
+    return text.replace(/[.\s]+$/, "");
+}
 // implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-opencode-kibi-plugin-v1
 /**
- * What a requirement says must stay true (its linked facts) and the decision
- * behind it (a linked ADR), read from its frontmatter links and
- * relationship-shard records. A retired requirement is not current policy, so
- * its grounding is not presented as something to keep true.
+ * What a requirement says must stay true and the decision behind it (a
+ * linked ADR), read from its frontmatter links and relationship-shard
+ * records. Each linked fact is shown as the claim it models, with its
+ * operator and members (a fact without typed fields by its title); without
+ * one the requirement's own statement is shown. Fact IDs are internal and
+ * never shown. A retired requirement is not current policy, so its grounding
+ * is not presented as something to keep true.
  */
 export function requirementGroundingLines(requirementId, summarize, options = {}) {
     const maxFacts = options.maxFacts ?? MAX_GROUNDING;
@@ -203,11 +301,24 @@ export function requirementGroundingLines(requirementId, summarize, options = {}
     ];
     const lines = [];
     if (facts.length > 0) {
-        const shown = facts
-            .slice(0, maxFacts)
-            .map((id) => describeEntity(summarize(id)));
-        const more = facts.length > maxFacts ? ` +${facts.length - maxFacts}` : "";
-        lines.push(`${requirementId} must keep true: ${shown.join("; ")}${more}.`);
+        const claims = [
+            ...new Set(facts
+                .map((id) => groundingText(summarize(id)))
+                .filter((sentence) => Boolean(sentence))
+                .map(withoutClosingStop)),
+        ];
+        const statement = requirement.statement
+            ? withoutClosingStop(requirement.statement)
+            : undefined;
+        const shown = claims.length > 0
+            ? claims.slice(0, maxFacts)
+            : statement
+                ? [statement]
+                : [];
+        const more = claims.length > maxFacts ? ` +${claims.length - maxFacts} more` : "";
+        if (shown.length > 0) {
+            lines.push(`${requirementId} must keep true: ${shown.map((claim) => truncate(claim, MAX_CLAIM)).join("; ")}${more}.`);
+        }
     }
     const adr = adrs[0];
     if (adr)

package/dist/usage-telemetry.d.ts

@@ -15,7 +15,10 @@
  * short-lived processes (hooks, the CLI) do not wait on the network.
  * `KIBI_TELEMETRY=0`, `DO_NOT_TRACK=1`, `kibi telemetry disable`, CI and test
  * runs, and sandboxes whose home directory is a temp directory (eval and
- * packaging harnesses) turn it off.
+ * packaging harnesses) turn it off. Runs of Kibi from a checkout of its own
+ * repository, and runs a harness marks with `KIBI_TELEMETRY_CHANNEL`, are
+ * still sent but carry a `channel` other than `release`, so they can be
+ * filtered out of real usage.
  */
 /** Public, write-only PostHog project key: it can send events, not read them. */
 export declare const DEFAULT_TELEMETRY_KEY = "phc_A5z8jRhD528abGJiTtPfgu4d4hpbEbfiJr9iUGn9TMsY";
@@ -33,7 +36,16 @@ export type TelemetryStatus = {
     /** Why telemetry is on or off, e.g. `KIBI_TELEMETRY=0` or `default`. */
     reason: string;
     directory: string;
+    /** The channel events carry, e.g. `release`, `source` or `agent-test`. */
+    channel: string;
+    /** Where the channel comes from. */
+    channelSource: TelemetryChannelSource;
 };
+/**
+ * `KIBI_TELEMETRY_CHANNEL` (a harness set it), `checkout` (Kibi runs from a
+ * checkout of its own repository) or `installed` (an installed package).
+ */
+export type TelemetryChannelSource = "KIBI_TELEMETRY_CHANNEL" | "checkout" | "installed";
 /** Summary of one Kibi operation run through MCP or the CLI. */
 export type OperationTelemetry = {
     interface: "mcp" | "cli";
@@ -85,6 +97,18 @@ export declare const SESSION_ENV_KEYS: readonly ["KIBI_SESSION_ID", "CLAUDE_CODE
 export declare function detectTelemetryHost(env?: Env): string | undefined;
 /** The host agent's session id from the environment, when it exposes one. */
 export declare function detectTelemetrySession(env?: Env): string | undefined;
+/**
+ * Where a run comes from: the `KIBI_TELEMETRY_CHANNEL` a harness sets (for
+ * example `agent-test`), `source` when Kibi runs from a checkout of its own
+ * repository (local development, the repository's own hooks, e2e and agent
+ * test rounds built from source), and `release` for an installed package.
+ */
+export declare function detectTelemetryChannel(env?: Env, moduleFile?: string | null): string;
+/** The channel in effect and where it comes from. */
+export declare function telemetryChannel(env?: Env, moduleFile?: string | null): {
+    channel: string;
+    source: TelemetryChannelSource;
+};
 /** Per-user directory holding the telemetry config and queue. */
 export declare function telemetryDirectory(env?: Env): string;
 export declare function readTelemetryConfig(env?: Env): TelemetryConfig;

package/dist/usage-telemetry.js

@@ -3,6 +3,7 @@ import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 /**
  * Anonymous usage telemetry shared by the CLI, the MCP server and the host
  * hooks.
@@ -20,7 +21,10 @@ import path from "node:path";
  * short-lived processes (hooks, the CLI) do not wait on the network.
  * `KIBI_TELEMETRY=0`, `DO_NOT_TRACK=1`, `kibi telemetry disable`, CI and test
  * runs, and sandboxes whose home directory is a temp directory (eval and
- * packaging harnesses) turn it off.
+ * packaging harnesses) turn it off. Runs of Kibi from a checkout of its own
+ * repository, and runs a harness marks with `KIBI_TELEMETRY_CHANNEL`, are
+ * still sent but carry a `channel` other than `release`, so they can be
+ * filtered out of real usage.
  */
 // implements REQ-kibi-anonymous-usage-telemetry
 /** Public, write-only PostHog project key: it can send events, not read them. */
@@ -183,6 +187,79 @@ function sandboxedHome(env) {
     const resolved = realDirectory(home);
     return resolved !== temp && resolved.startsWith(`${temp}${path.sep}`);
 }
+/** The Kibi monorepo root's package name. */
+const KIBI_REPOSITORY_PACKAGE = "kibi";
+/** This module's file, or undefined when a bundle format drops `import.meta.url`. */
+function thisModuleFile() {
+    try {
+        const url = import.meta.url;
+        return typeof url === "string" && url !== ""
+            ? fileURLToPath(url)
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a file belongs to a checkout of the Kibi repository rather than to
+ * an installed package. Installed copies live under `node_modules` or in a
+ * host's plugin cache; a checkout has the monorepo root `package.json` (named
+ * `kibi`, with a `packages/agent-core` workspace) above the file.
+ */
+function insideKibiCheckout(file) {
+    const resolved = realDirectory(file);
+    if (resolved.split(/[\\/]/).includes("node_modules"))
+        return false;
+    let current = path.dirname(resolved);
+    for (;;) {
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(current, "package.json"), "utf8"));
+            if (manifest.name === KIBI_REPOSITORY_PACKAGE &&
+                fs.existsSync(path.join(current, "packages", "agent-core"))) {
+                return true;
+            }
+        }
+        catch {
+            // No readable manifest here; keep walking up.
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
+const checkoutCache = new Map();
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * Where a run comes from: the `KIBI_TELEMETRY_CHANNEL` a harness sets (for
+ * example `agent-test`), `source` when Kibi runs from a checkout of its own
+ * repository (local development, the repository's own hooks, e2e and agent
+ * test rounds built from source), and `release` for an installed package.
+ */
+export function detectTelemetryChannel(env = process.env, moduleFile = thisModuleFile() ?? null) {
+    return telemetryChannel(env, moduleFile).channel;
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/** The channel in effect and where it comes from. */
+export function telemetryChannel(env = process.env, moduleFile = thisModuleFile() ?? null) {
+    const explicit = env.KIBI_TELEMETRY_CHANNEL?.trim();
+    if (explicit)
+        return {
+            channel: telemetryCategory(explicit) ?? "release",
+            source: "KIBI_TELEMETRY_CHANNEL",
+        };
+    if (!moduleFile)
+        return { channel: "release", source: "installed" };
+    let fromCheckout = checkoutCache.get(moduleFile);
+    if (fromCheckout === undefined) {
+        fromCheckout = insideKibiCheckout(moduleFile);
+        checkoutCache.set(moduleFile, fromCheckout);
+    }
+    return fromCheckout
+        ? { channel: "source", source: "checkout" }
+        : { channel: "release", source: "installed" };
+}
 // implements REQ-kibi-anonymous-usage-telemetry
 /** Per-user directory holding the telemetry config and queue. */
 export function telemetryDirectory(env = process.env) {
@@ -230,10 +307,13 @@ export function setTelemetryPreference(preference, env = process.env) {
  */
 export function telemetryStatus(env = process.env) {
     const directory = telemetryDirectory(env);
+    const { channel, source } = telemetryChannel(env);
     const status = (enabled, reason) => ({
         enabled,
         reason,
         directory,
+        channel,
+        channelSource: source,
     });
     const explicit = flagValue(env.KIBI_TELEMETRY);
     if (explicit === false)
@@ -425,6 +505,7 @@ function baseProperties(source, env) {
             detectTelemetryHost(env) ||
             "unknown",
         remote: remoteEnvironment(env),
+        channel: detectTelemetryChannel(env),
         session: sessionProperty(source, env),
         os: process.platform,
         arch: process.arch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-agent-core",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",