kibi-agent-core 0.9.1 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # kibi-agent-core
 
+## 0.11.0
+
+### Minor Changes
+
+- 43d4366: Usage telemetry data is cleaner and more complete. Telemetry is now off when the home directory lies inside the temp directory, as eval, packaging and end-to-end harnesses set it, so each harness run no longer counts as a new install; Kibi's own eval and packed-test sandboxes also set `KIBI_TELEMETRY=0`. Events now name the host agent from `CLAUDECODE`, `CURSOR_AGENT`, `CODEX_SANDBOX`, `GEMINI_CLI`, `OPENCODE`, `AI_AGENT` or the MCP client name, carry a hashed host session id in every host, and say whether they come from a hosted cloud workspace. Failed CLI commands and MCP tool results now carry a fixed error category: the result's error code (for example `upsert_dry_run_invalid`), the failing `kibi doctor` checks, or the `kibi migrate` approval problem. `kibi migrate --apply-safe` now prints the current plan hash when the approved hash is missing or out of date.
+
+  Hooks in Claude Code, Codex, Cursor, ZCode and OpenCode now all send the anonymous `kibi_hook` event (before, only Claude Code did, and only in diagnostic mode for the others), and each hook remembers, as hashes in `telemetry-sessions.json`, which host session last ran in the workspace. CLI and MCP events take the session id from `KIBI_SESSION_ID`, `CLAUDE_CODE_SESSION_ID` or `CODEX_THREAD_ID` when the host exposes one, and otherwise from that workspace marker (at most 30 minutes old), so events from Cursor and OpenCode sessions, which expose no session variable, can be grouped too. Every host's hook also sends the queue when it is due, and right away at the end of a turn.
+
+### Patch Changes
+
+- ce41f02: Agents now keep a signoff in the pull request it approves. The guidance used to time the signoff as an end-of-work step and said only that an agent must never set `approved_by` itself, so agents often opened the pull request first and then carried the person's answer in a separate follow-up pull request.
+  - kibi-usage 2.37.0, kibi-decisions 1.5.0 and kibi-commit-review 1.4.0 (and the signoff-views resource) say to ask for the signoff before opening or merging the pull request, and to record the person's answer (their name in `approved_by` or a `*_waiver_approved_by` field, their words in `origin.ref` or `approval_ref`) on the same branch and pull request. Writing down an answer the person gave is not self-approval. A pull request that only carries a signoff, firmness or waiver approval is ruled out.
+  - The stop-hook signoff reminder (Claude Code, Codex, Cursor, ZCode) adds the same rule. So do the `agent-requirement-unapproved` check action, the `dimension_unrepresented` repair hint and the waiver lines of `kibi proof explain`.
+
+## 0.10.0
+
+### Minor Changes
+
+- d89c1d2: Kibi now sends anonymous usage statistics, so its maintainers can see which operations people use, how long they take and how they fail, including in cloud and ephemeral environments where the local diagnostic log is lost. Only fixed names, statuses, durations, error categories, versions and platform are sent. Code, paths, queries, KB content and repository names never are. Turn it off with `kibi telemetry disable`, `KIBI_TELEMETRY=0` or `DO_NOT_TRACK=1`. It is also off in CI and test runs.
+  - kibi-agent-core adds `usage-telemetry`, a shared queue and batch sender for PostHog, with a random install id, hashed session ids and no person profiles.
+  - kibi-mcp records one `kibi_operation` event per tool call, sends the queue every minute and on shutdown, and prints a one-time notice to stderr.
+  - kibi-cli records one event per command, adds `kibi telemetry status|enable|disable`, and prints the one-time notice.
+  - kibi-claude records one `kibi_hook` event per hook decision and sends the queue from the Stop hook.
+
 ## 0.9.1
 
 ### Patch Changes

package/dist/decision-guard.js

@@ -260,7 +260,7 @@ export function claimSignoffReminder(session, workspaceRoot) {
 export function signoffReminder() {
     return [
         "Kibi: this session recorded or changed requirements, and the person has not seen them as a signoff view.",
-        "Before reporting the work done or asking to commit, run `kibi signoff` and put its output in the reply unchanged; a requirement the agent wrote waits for the person's approval, so ask for it with this view, never in your own words. When replies go through a messaging tool, pass the output there as the message text, and share `.kb/briefs/signoff/latest.html` only as a rendered page (the Artifact tool in Claude apps), never as an attached file, which chat apps show as raw source (kibi-decisions, resources/signoff-views.md).",
+        "Before reporting the work done, asking to commit, or opening or merging the pull request, run `kibi signoff` and put its output in the reply unchanged; a requirement the agent wrote waits for the person's approval, so ask for it with this view, never in your own words. When they answer, record their answer on the same branch and push it to the same pull request, never to a separate one. When replies go through a messaging tool, pass the output there as the message text, and share `.kb/briefs/signoff/latest.html` only as a rendered page (the Artifact tool in Claude apps), never as an attached file, which chat apps show as raw source (kibi-decisions, resources/signoff-views.md).",
     ].join("\n");
 }
 function readSettled(file) {

package/dist/hook-usage-log.d.ts

@@ -35,6 +35,8 @@ export declare function hookTelemetryEnabled(env?: NodeJS.ProcessEnv): boolean;
 export type HookUsageRow = {
     /** Host agent, e.g. `claude-code`, `cursor`, `codex`, `zcode`, `opencode`. */
     host: string;
+    /** Adapter npm package; defaults to `kibi-<host>` (`kibi-claude` for Claude Code). */
+    packageName?: string | undefined;
     /** Version of the adapter package that wrote the row, when known. */
     packageVersion?: string | null | undefined;
     workspaceRoot: string;
@@ -44,7 +46,15 @@ export type HookUsageRow = {
     trace: HookTrace;
     startedAt: Date;
 };
-/** Append one hook row to `.kb/usage.log` when the operator opted in. */
+/**
+ * Whether a host should build hook traces at all: for the opt-in
+ * `.kb/usage.log` rows or for anonymous usage telemetry.
+ */
+export declare function hookTracesWanted(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Record one hook decision: an anonymous summary event (unless telemetry is
+ * off) and, when the operator opted in, the detailed `.kb/usage.log` row.
+ */
 export declare function appendHookUsage(row: HookUsageRow, env?: NodeJS.ProcessEnv): void;
 /**
  * Trace for a tool call that ran a Kibi operation through MCP or the
@@ -59,6 +69,17 @@ export declare function kbUsageTrace(toolName: string | undefined, toolInput: un
 export declare function editTraces(relativePaths: readonly string[], requirementIdsFor: (relativePath: string) => string[]): HookTrace[];
 /** Append one row per trace, sharing the call's host, session and tool. */
 export declare function appendHookUsageRows(row: Omit<HookUsageRow, "trace">, traces: readonly HookTrace[], env?: NodeJS.ProcessEnv): void;
+/**
+ * End-of-hook bookkeeping every host runs: remember the host session for the
+ * workspace, so CLI and MCP events from that workspace can carry it, and send
+ * the anonymous telemetry queue when it is due, or always at the end of a
+ * turn. Never throws.
+ */
+export declare function finishHookTelemetry(input: {
+    readonly event: string;
+    readonly workspaceRoot: string | undefined;
+    readonly sessionId: string | undefined;
+}, env?: NodeJS.ProcessEnv): Promise<void>;
 /**
  * Version of the adapter package whose `package.json` sits at
  * `packageJsonPath`, or null when it cannot be read.

package/dist/hook-usage-log.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { hostKbOperation } from "./kb-mcp-tools.js";
 import { classifyPath } from "./path-policy.js";
+import { flushTelemetry, recordHookTelemetry, rememberHookSession, telemetryEnabled, } from "./usage-telemetry.js";
 // implements REQ-claude-hook-usage-telemetry-v2, REQ-kibi-telemetry-acceptance-gate-v2
 /** Hook actions the acceptance report reads; hosts emit these names. */
 export const HOOK_ACTION_EDITED = "edited";
@@ -15,9 +16,38 @@ export function hookTelemetryEnabled(env = process.env) {
     return value === "1" || value === "true";
 }
 // implements REQ-claude-hook-usage-telemetry-v2
-/** Append one hook row to `.kb/usage.log` when the operator opted in. */
+/**
+ * Whether a host should build hook traces at all: for the opt-in
+ * `.kb/usage.log` rows or for anonymous usage telemetry.
+ */
+export function hookTracesWanted(env = process.env) {
+    return hookTelemetryEnabled(env) || telemetryEnabled(env);
+}
+function adapterPackage(host) {
+    return host === "claude-code" ? "kibi-claude" : `kibi-${host}`;
+}
+// implements REQ-claude-hook-usage-telemetry-v2, REQ-kibi-anonymous-usage-telemetry
+/**
+ * Record one hook decision: an anonymous summary event (unless telemetry is
+ * off) and, when the operator opted in, the detailed `.kb/usage.log` row.
+ */
 export function appendHookUsage(row, env = process.env) {
-    if (!hookTelemetryEnabled(env) || row.trace.action === undefined)
+    if (row.trace.action === undefined)
+        return;
+    recordHookTelemetry({
+        packageName: row.packageName ?? adapterPackage(row.host),
+        packageVersion: row.packageVersion,
+        host: row.host,
+        sessionId: row.sessionId,
+    }, {
+        hookEvent: row.event,
+        hookAction: row.trace.action,
+        pathKind: row.trace.pathKind,
+        kbOperation: row.trace.kbOperation,
+        kbUsedBefore: row.trace.kbUsedBefore,
+        requirementCount: row.trace.requirementIds?.length,
+    }, env);
+    if (!hookTelemetryEnabled(env))
         return;
     const finishedAt = new Date();
     const { trace } = row;
@@ -85,11 +115,32 @@ export function editTraces(relativePaths, requirementIdsFor) {
 // implements REQ-claude-hook-usage-telemetry-v2
 /** Append one row per trace, sharing the call's host, session and tool. */
 export function appendHookUsageRows(row, traces, env = process.env) {
-    if (!hookTelemetryEnabled(env))
+    if (!hookTracesWanted(env))
         return;
     for (const trace of traces)
         appendHookUsage({ ...row, trace }, env);
 }
+/** Host events that end a turn or a session: the queue is sent right away. */
+const TURN_END_EVENTS = new Set(["stop", "sessionend"]);
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * End-of-hook bookkeeping every host runs: remember the host session for the
+ * workspace, so CLI and MCP events from that workspace can carry it, and send
+ * the anonymous telemetry queue when it is due, or always at the end of a
+ * turn. Never throws.
+ */
+export async function finishHookTelemetry(input, env = process.env) {
+    try {
+        if (input.workspaceRoot && input.sessionId) {
+            rememberHookSession(input.workspaceRoot, input.sessionId, env);
+        }
+        const turnEnd = TURN_END_EVENTS.has(input.event.toLowerCase().replace(/[^a-z]/g, ""));
+        await flushTelemetry({ force: turnEnd }, env);
+    }
+    catch {
+        // Telemetry is best effort and must never disturb the hook.
+    }
+}
 // implements REQ-claude-hook-usage-telemetry-v2
 /**
  * Version of the adapter package whose `package.json` sits at

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from "./knowledge-index.js";
 export * from "./path-policy.js";
 export * from "./snippets.js";
 export * from "./requirement-candidates.js";
+export * from "./usage-telemetry.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export * from "./knowledge-index.js";
 export * from "./path-policy.js";
 export * from "./snippets.js";
 export * from "./requirement-candidates.js";
+export * from "./usage-telemetry.js";

package/dist/usage-telemetry.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Anonymous usage telemetry shared by the CLI, the MCP server and the host
+ * hooks.
+ *
+ * `.kb/usage.log` stays the detailed, opt-in diagnostic record and never
+ * leaves the machine. This module sends a much smaller summary to the Kibi
+ * PostHog project so maintainers can see which operations people run, how
+ * long they take and how they fail. Events carry only fixed vocabulary
+ * (operation and command names, statuses, error categories, path kinds),
+ * durations, versions and platform; never paths, queries, entity ids, KB
+ * content, repository names or error messages. The install id is random and
+ * the host session id is hashed.
+ *
+ * Events are appended to a per-user queue file and sent in batches, so
+ * 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.
+ */
+/** Public, write-only PostHog project key: it can send events, not read them. */
+export declare const DEFAULT_TELEMETRY_KEY = "phc_A5z8jRhD528abGJiTtPfgu4d4hpbEbfiJr9iUGn9TMsY";
+export declare const DEFAULT_TELEMETRY_HOST = "https://eu.i.posthog.com";
+export declare const TELEMETRY_DOCS_URL = "https://looted.github.io/kibi/guide/telemetry.html";
+type Env = NodeJS.ProcessEnv;
+export type TelemetryPreference = "enabled" | "disabled";
+export type TelemetryConfig = {
+    installId?: string;
+    preference?: TelemetryPreference;
+    noticeShownAt?: string;
+};
+export type TelemetryStatus = {
+    enabled: boolean;
+    /** Why telemetry is on or off, e.g. `KIBI_TELEMETRY=0` or `default`. */
+    reason: string;
+    directory: string;
+};
+/** Summary of one Kibi operation run through MCP or the CLI. */
+export type OperationTelemetry = {
+    interface: "mcp" | "cli";
+    /** Registered MCP tool or CLI command name. */
+    operation: string;
+    status: "success" | "error";
+    durationMs: number;
+    /** Fixed diagnostic category such as `tool_timeout`, when known. */
+    errorCategory?: string | undefined;
+    exitCode?: number | undefined;
+};
+/** Summary of one host hook decision. */
+export type HookTelemetry = {
+    hookEvent: string;
+    hookAction: string;
+    pathKind?: string | undefined;
+    kbOperation?: string | undefined;
+    kbUsedBefore?: boolean | undefined;
+    requirementCount?: number | undefined;
+};
+/** Who is sending: the package, its version and the host agent. */
+export type TelemetrySource = {
+    /** npm package name, e.g. `kibi-cli`, `kibi-mcp`, `kibi-claude`. */
+    packageName: string;
+    packageVersion?: string | null | undefined;
+    /** Host agent, e.g. `claude-code`, `cursor`, `codex`, or `unknown`. */
+    host?: string | undefined;
+    /** Host session id; only its hash is sent. */
+    sessionId?: string | null | undefined;
+    /**
+     * Workspace the CLI or MCP server works in. Without a session id of its
+     * own, the event takes the session a host hook last reported there.
+     */
+    workspaceRoot?: string | undefined;
+};
+/** Variables CI providers set; any non-false value marks a CI run. */
+export declare const CI_ENV_KEYS: readonly ["CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI", "BUILDKITE", "CIRCLECI", "TRAVIS", "TF_BUILD", "JENKINS_URL", "TEAMCITY_VERSION", "BITBUCKET_BUILD_NUMBER", "CODEBUILD_BUILD_ID", "DRONE", "APPVEYOR", "SEMAPHORE", "BUILDKITE_BUILD_ID", "CF_BUILD_ID", "HEROKU_TEST_RUN_ID"];
+/** Variables test runners set for the code under test (`NAME=value` must match). */
+export declare const TEST_ENV_KEYS: readonly ["NODE_ENV=test", "JEST_WORKER_ID", "VITEST", "VITEST_WORKER_ID", "NODE_TEST_CONTEXT"];
+/** Variables an agent host sets for the processes it starts, in priority order. */
+export declare const HOST_ENV_KEYS: readonly [readonly ["CLAUDECODE=1", "claude-code"], readonly ["CURSOR_AGENT=1", "cursor"], readonly ["CODEX_SANDBOX", "codex"], readonly ["CODEX_THREAD_ID", "codex"], readonly ["GEMINI_CLI=1", "gemini-cli"], readonly ["OPENCODE=1", "opencode"]];
+/** Variables that carry the host agent's session id; only its hash is sent. */
+export declare const SESSION_ENV_KEYS: readonly ["KIBI_SESSION_ID", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID"];
+/**
+ * The agent host running Kibi, from an explicit `KIBI_HOST`/`KIBI_MCP_HOST`,
+ * the variables hosts set for their children, or the `AI_AGENT` convention
+ * (`claude-code_2-1-3_agent`). Undefined when nothing names one.
+ */
+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;
+/** Per-user directory holding the telemetry config and queue. */
+export declare function telemetryDirectory(env?: Env): string;
+export declare function readTelemetryConfig(env?: Env): TelemetryConfig;
+/**
+ * Persist the user's choice. Disabling also deletes anything still queued,
+ * so nothing recorded before the choice is sent afterwards.
+ */
+export declare function setTelemetryPreference(preference: TelemetryPreference, env?: Env): void;
+/**
+ * Whether events are recorded and sent, and why. Explicit opt-outs win over
+ * everything. CI and test runs are off even after `kibi telemetry enable`;
+ * only an explicit `KIBI_TELEMETRY=1` sends from them.
+ */
+export declare function telemetryStatus(env?: Env): TelemetryStatus;
+export declare function telemetryEnabled(env?: Env): boolean;
+/** Stable one-way hash, so a session can be grouped without revealing its id. */
+export declare function hashTelemetryId(value: string): string;
+/**
+ * The notice users see before the first event is sent, or null once it was
+ * shown. Callers that can reach the user (CLI and MCP stderr) print it.
+ */
+export declare function takeTelemetryNotice(env?: Env): string | null;
+/**
+ * Remember which host session last ran a hook in a workspace. Every host
+ * hands its hooks the session id, but only some expose it to the CLI and MCP
+ * server through the environment. Only hashes are stored: of the workspace
+ * path and of the session id.
+ */
+export declare function rememberHookSession(workspaceRoot: string, sessionId: string, env?: Env): void;
+/**
+ * Hashed session a host hook recently reported for this directory or the
+ * nearest ancestor that has one, or undefined.
+ */
+export declare function workspaceSessionHash(startDirectory: string, env?: Env): string | undefined;
+/**
+ * An error category as sent: fixed identifiers such as `tool_timeout` or
+ * `UPSERT_DRY_RUN_INVALID` pass, lower-cased; anything that looks like free
+ * text is replaced, so a message can never leak through this field.
+ */
+export declare function telemetryCategory(value: string | undefined): string | null;
+export declare function recordOperationTelemetry(source: TelemetrySource, operation: OperationTelemetry, env?: Env): void;
+export declare function recordHookTelemetry(source: TelemetrySource, hook: HookTelemetry, env?: Env): void;
+export declare function clearTelemetryQueue(env?: Env): void;
+export type FlushOptions = {
+    /** Send even when the queue is small and recent (process exit, Stop hook). */
+    force?: boolean;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+};
+/**
+ * Send queued events in one batch when a flush is due (or forced). Returns
+ * the number of events sent. A failed send puts the events back for the next
+ * flush; nothing here throws.
+ */
+export declare function flushTelemetry(options?: FlushOptions, env?: Env): Promise<number>;
+export {};

package/dist/usage-telemetry.js

@@ -0,0 +1,660 @@
+// implements REQ-kibi-anonymous-usage-telemetry
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Anonymous usage telemetry shared by the CLI, the MCP server and the host
+ * hooks.
+ *
+ * `.kb/usage.log` stays the detailed, opt-in diagnostic record and never
+ * leaves the machine. This module sends a much smaller summary to the Kibi
+ * PostHog project so maintainers can see which operations people run, how
+ * long they take and how they fail. Events carry only fixed vocabulary
+ * (operation and command names, statuses, error categories, path kinds),
+ * durations, versions and platform; never paths, queries, entity ids, KB
+ * content, repository names or error messages. The install id is random and
+ * the host session id is hashed.
+ *
+ * Events are appended to a per-user queue file and sent in batches, so
+ * 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.
+ */
+// implements REQ-kibi-anonymous-usage-telemetry
+/** Public, write-only PostHog project key: it can send events, not read them. */
+export const DEFAULT_TELEMETRY_KEY = "phc_A5z8jRhD528abGJiTtPfgu4d4hpbEbfiJr9iUGn9TMsY";
+// implements REQ-kibi-anonymous-usage-telemetry
+export const DEFAULT_TELEMETRY_HOST = "https://eu.i.posthog.com";
+// implements REQ-kibi-anonymous-usage-telemetry
+export const TELEMETRY_DOCS_URL = "https://looted.github.io/kibi/guide/telemetry.html";
+const QUEUE_FILE = "telemetry-queue.jsonl";
+const SESSIONS_FILE = "telemetry-sessions.json";
+/** A hook-recorded session older than this no longer names the workspace's session. */
+const SESSION_MARKER_MAX_AGE_MS = 30 * 60 * 1000;
+const MAX_SESSION_MARKERS = 200;
+const CONFIG_FILE = "telemetry.json";
+const SENDING_SUFFIX = ".sending";
+/** Queue size that makes a flush due regardless of age. */
+const FLUSH_BATCH_EVENTS = 20;
+/** Age of the oldest queued event that makes a flush due. */
+const FLUSH_MAX_AGE_MS = 5 * 60 * 1000;
+/** A claimed batch older than this was left by a process that died. */
+const STALE_CLAIM_MS = 10 * 60 * 1000;
+/** Queued events older than this are dropped instead of sent. */
+const MAX_EVENT_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/** The queue stops growing past this size when sends keep failing. */
+const MAX_QUEUE_BYTES = 1024 * 1024;
+const DEFAULT_FLUSH_TIMEOUT_MS = 1500;
+function flagValue(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (normalized === undefined || normalized === "")
+        return undefined;
+    if (["1", "true", "yes", "on"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "off"].includes(normalized))
+        return false;
+    return undefined;
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/** Variables CI providers set; any non-false value marks a CI run. */
+export const CI_ENV_KEYS = [
+    "CI",
+    "CONTINUOUS_INTEGRATION",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "BUILDKITE",
+    "CIRCLECI",
+    "TRAVIS",
+    "TF_BUILD",
+    "JENKINS_URL",
+    "TEAMCITY_VERSION",
+    "BITBUCKET_BUILD_NUMBER",
+    "CODEBUILD_BUILD_ID",
+    "DRONE",
+    "APPVEYOR",
+    "SEMAPHORE",
+    "BUILDKITE_BUILD_ID",
+    "CF_BUILD_ID",
+    "HEROKU_TEST_RUN_ID",
+];
+// implements REQ-kibi-anonymous-usage-telemetry
+/** Variables test runners set for the code under test (`NAME=value` must match). */
+export const TEST_ENV_KEYS = [
+    "NODE_ENV=test",
+    "JEST_WORKER_ID",
+    "VITEST",
+    "VITEST_WORKER_ID",
+    "NODE_TEST_CONTEXT",
+];
+function automationName(env, keys) {
+    for (const key of keys) {
+        const [name, expected] = key.split("=");
+        const value = env[name]?.trim();
+        if (!value)
+            continue;
+        if (expected !== undefined) {
+            if (value === expected)
+                return key;
+            continue;
+        }
+        if (flagValue(value) !== false)
+            return name;
+    }
+    return undefined;
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/** Variables an agent host sets for the processes it starts, in priority order. */
+export const HOST_ENV_KEYS = [
+    ["CLAUDECODE=1", "claude-code"],
+    ["CURSOR_AGENT=1", "cursor"],
+    ["CODEX_SANDBOX", "codex"],
+    ["CODEX_THREAD_ID", "codex"],
+    ["GEMINI_CLI=1", "gemini-cli"],
+    ["OPENCODE=1", "opencode"],
+];
+// implements REQ-kibi-anonymous-usage-telemetry
+/** Variables that carry the host agent's session id; only its hash is sent. */
+export const SESSION_ENV_KEYS = [
+    "KIBI_SESSION_ID",
+    "CLAUDE_CODE_SESSION_ID",
+    "CODEX_THREAD_ID",
+];
+/** `Claude Code`, `claude_code` and `claude-code` name the same host. */
+function hostKey(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * The agent host running Kibi, from an explicit `KIBI_HOST`/`KIBI_MCP_HOST`,
+ * the variables hosts set for their children, or the `AI_AGENT` convention
+ * (`claude-code_2-1-3_agent`). Undefined when nothing names one.
+ */
+export function detectTelemetryHost(env = process.env) {
+    const explicit = env.KIBI_HOST?.trim() || env.KIBI_MCP_HOST?.trim();
+    if (explicit)
+        return hostKey(explicit) || undefined;
+    for (const [key, host] of HOST_ENV_KEYS) {
+        if (automationName(env, [key]))
+            return host;
+    }
+    const agent = env.AI_AGENT?.trim().split("_")[0];
+    return agent ? hostKey(agent) || undefined : undefined;
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/** The host agent's session id from the environment, when it exposes one. */
+export function detectTelemetrySession(env = process.env) {
+    for (const key of SESSION_ENV_KEYS) {
+        const value = env[key]?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/** Whether the process runs in a hosted cloud workspace rather than on a laptop. */
+function remoteEnvironment(env) {
+    return (flagValue(env.CLAUDE_CODE_REMOTE) === true ||
+        flagValue(env.CODESPACES) === true ||
+        Boolean(env.GITPOD_WORKSPACE_ID?.trim()));
+}
+function realDirectory(directory) {
+    try {
+        return fs.realpathSync(directory);
+    }
+    catch {
+        return path.resolve(directory);
+    }
+}
+/**
+ * Eval, packaging and e2e harnesses give each run a fresh home under the temp
+ * directory, so every run would count as a new install. A real user's home
+ * never lives there.
+ */
+function sandboxedHome(env) {
+    const home = (env.HOME ?? env.USERPROFILE)?.trim();
+    if (!home)
+        return false;
+    const temp = realDirectory(os.tmpdir());
+    const resolved = realDirectory(home);
+    return resolved !== temp && resolved.startsWith(`${temp}${path.sep}`);
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/** Per-user directory holding the telemetry config and queue. */
+export function telemetryDirectory(env = process.env) {
+    const explicit = env.KIBI_TELEMETRY_DIR?.trim();
+    if (explicit)
+        return explicit;
+    if (process.platform === "win32" && env.LOCALAPPDATA) {
+        return path.join(env.LOCALAPPDATA, "kibi");
+    }
+    const stateHome = env.XDG_STATE_HOME?.trim();
+    return path.join(stateHome || path.join(env.HOME || os.homedir(), ".local", "state"), "kibi");
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+export function readTelemetryConfig(env = process.env) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(telemetryDirectory(env), CONFIG_FILE), "utf8"));
+        return typeof parsed === "object" && parsed !== null
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeTelemetryConfig(config, env) {
+    const directory = telemetryDirectory(env);
+    fs.mkdirSync(directory, { recursive: true });
+    fs.writeFileSync(path.join(directory, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * Persist the user's choice. Disabling also deletes anything still queued,
+ * so nothing recorded before the choice is sent afterwards.
+ */
+export function setTelemetryPreference(preference, env = process.env) {
+    writeTelemetryConfig({ ...readTelemetryConfig(env), preference }, env);
+    if (preference === "disabled")
+        clearTelemetryQueue(env);
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * Whether events are recorded and sent, and why. Explicit opt-outs win over
+ * everything. CI and test runs are off even after `kibi telemetry enable`;
+ * only an explicit `KIBI_TELEMETRY=1` sends from them.
+ */
+export function telemetryStatus(env = process.env) {
+    const directory = telemetryDirectory(env);
+    const status = (enabled, reason) => ({
+        enabled,
+        reason,
+        directory,
+    });
+    const explicit = flagValue(env.KIBI_TELEMETRY);
+    if (explicit === false)
+        return status(false, "KIBI_TELEMETRY=0");
+    if (flagValue(env.DO_NOT_TRACK) === true) {
+        return status(false, "DO_NOT_TRACK=1");
+    }
+    const preference = readTelemetryConfig(env).preference;
+    if (preference === "disabled") {
+        return status(false, "disabled with `kibi telemetry disable`");
+    }
+    if (telemetryKey(env) === "")
+        return status(false, "no telemetry key");
+    if (explicit === true)
+        return status(true, "KIBI_TELEMETRY=1");
+    // Read through a variable: bundlers inline `process.env.NODE_ENV`.
+    const processEnv = process.env;
+    // CI and test runs are checked in both the given env and the process env,
+    // so a suite that passes its own env object cannot leak events either.
+    const ciName = automationName(env, CI_ENV_KEYS) ?? automationName(processEnv, CI_ENV_KEYS);
+    if (ciName)
+        return status(false, `CI environment (${ciName})`);
+    const testName = automationName(env, TEST_ENV_KEYS) ??
+        automationName(processEnv, TEST_ENV_KEYS);
+    if (testName)
+        return status(false, `test environment (${testName})`);
+    if (sandboxedHome(env)) {
+        return status(false, "sandboxed home in the temp directory (harness run)");
+    }
+    if (preference === "enabled") {
+        return status(true, "enabled with `kibi telemetry enable`");
+    }
+    return status(true, "on by default; anonymous, opt-out");
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+export function telemetryEnabled(env = process.env) {
+    return telemetryStatus(env).enabled;
+}
+function telemetryKey(env) {
+    const override = env.KIBI_TELEMETRY_KEY;
+    return (override === undefined ? DEFAULT_TELEMETRY_KEY : override).trim();
+}
+function telemetryHost(env) {
+    return (env.KIBI_TELEMETRY_HOST?.trim() || DEFAULT_TELEMETRY_HOST).replace(/\/+$/, "");
+}
+function installId(env) {
+    const config = readTelemetryConfig(env);
+    if (typeof config.installId === "string" && config.installId !== "") {
+        return config.installId;
+    }
+    const created = randomUUID();
+    try {
+        writeTelemetryConfig({ ...config, installId: created }, env);
+    }
+    catch {
+        // An unwritable directory still lets this process send with a fresh id.
+    }
+    return created;
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/** Stable one-way hash, so a session can be grouped without revealing its id. */
+export function hashTelemetryId(value) {
+    return createHash("sha256")
+        .update("kibi-telemetry\0")
+        .update(value)
+        .digest("hex")
+        .slice(0, 16);
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * The notice users see before the first event is sent, or null once it was
+ * shown. Callers that can reach the user (CLI and MCP stderr) print it.
+ */
+export function takeTelemetryNotice(env = process.env) {
+    if (!telemetryEnabled(env))
+        return null;
+    const config = readTelemetryConfig(env);
+    if (config.noticeShownAt)
+        return null;
+    try {
+        writeTelemetryConfig({ ...config, noticeShownAt: new Date().toISOString() }, env);
+    }
+    catch {
+        // Without a writable config the notice would repeat on every run.
+        return null;
+    }
+    return [
+        "Kibi collects anonymous usage statistics (operation names, durations, error categories and versions) to improve Kibi.",
+        "It never sends code, file paths, queries, KB content or repository names.",
+        `Turn it off with \`kibi telemetry disable\` or KIBI_TELEMETRY=0. Details: ${TELEMETRY_DOCS_URL}`,
+    ].join("\n");
+}
+function runtimeName() {
+    return typeof globalThis.Bun === "undefined"
+        ? "node"
+        : "bun";
+}
+function sessionMarkersPath(env) {
+    return path.join(telemetryDirectory(env), SESSIONS_FILE);
+}
+function readSessionMarkers(env) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(sessionMarkersPath(env), "utf8"));
+        return parsed !== null &&
+            typeof parsed === "object" &&
+            !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function workspaceKey(workspaceRoot) {
+    return hashTelemetryId(`workspace\0${path.resolve(workspaceRoot)}`);
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * Remember which host session last ran a hook in a workspace. Every host
+ * hands its hooks the session id, but only some expose it to the CLI and MCP
+ * server through the environment. Only hashes are stored: of the workspace
+ * path and of the session id.
+ */
+export function rememberHookSession(workspaceRoot, sessionId, env = process.env) {
+    if (!sessionId.trim() || !telemetryEnabled(env))
+        return;
+    const now = Date.now();
+    const markers = readSessionMarkers(env);
+    markers[workspaceKey(workspaceRoot)] = {
+        session: hashTelemetryId(sessionId.trim()),
+        at: now,
+    };
+    const kept = Object.entries(markers)
+        .filter(([, marker]) => typeof marker?.at === "number" &&
+        now - marker.at <= SESSION_MARKER_MAX_AGE_MS)
+        .sort(([, left], [, right]) => right.at - left.at)
+        .slice(0, MAX_SESSION_MARKERS);
+    try {
+        const file = sessionMarkersPath(env);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+        fs.writeFileSync(temporary, JSON.stringify(Object.fromEntries(kept)));
+        fs.renameSync(temporary, file);
+    }
+    catch {
+        // Telemetry is best effort and must never disturb the hook.
+    }
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * Hashed session a host hook recently reported for this directory or the
+ * nearest ancestor that has one, or undefined.
+ */
+export function workspaceSessionHash(startDirectory, env = process.env) {
+    const markers = readSessionMarkers(env);
+    const now = Date.now();
+    let current = path.resolve(startDirectory);
+    for (;;) {
+        const marker = markers[workspaceKey(current)];
+        if (marker &&
+            typeof marker.session === "string" &&
+            typeof marker.at === "number" &&
+            now - marker.at <= SESSION_MARKER_MAX_AGE_MS) {
+            return marker.session;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+function sessionProperty(source, env) {
+    const sessionId = source.sessionId?.trim() || detectTelemetrySession(env);
+    if (sessionId)
+        return hashTelemetryId(sessionId);
+    return source.workspaceRoot
+        ? (workspaceSessionHash(source.workspaceRoot, env) ?? null)
+        : null;
+}
+function baseProperties(source, env) {
+    return {
+        distinct_id: installId(env),
+        $process_person_profile: false,
+        $geoip_disable: true,
+        $lib: "kibi",
+        package: source.packageName,
+        package_version: source.packageVersion ?? null,
+        host: (source.host?.trim() && hostKey(source.host)) ||
+            detectTelemetryHost(env) ||
+            "unknown",
+        remote: remoteEnvironment(env),
+        session: sessionProperty(source, env),
+        os: process.platform,
+        arch: process.arch,
+        runtime: runtimeName(),
+        runtime_version: process.versions.node.split(".")[0] ?? null,
+    };
+}
+function queuePath(env) {
+    return path.join(telemetryDirectory(env), QUEUE_FILE);
+}
+function appendEvent(event, env) {
+    try {
+        const file = queuePath(env);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        try {
+            if (fs.statSync(file).size > MAX_QUEUE_BYTES)
+                return;
+        }
+        catch {
+            // No queue yet.
+        }
+        fs.appendFileSync(file, `${JSON.stringify(event)}\n`, "utf8");
+    }
+    catch {
+        // Telemetry is best effort and must never disturb the caller.
+    }
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * An error category as sent: fixed identifiers such as `tool_timeout` or
+ * `UPSERT_DRY_RUN_INVALID` pass, lower-cased; anything that looks like free
+ * text is replaced, so a message can never leak through this field.
+ */
+export function telemetryCategory(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return null;
+    return /^[A-Za-z0-9_.:+-]{1,160}$/.test(trimmed)
+        ? trimmed.toLowerCase()
+        : "unclassified";
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+export function recordOperationTelemetry(source, operation, env = process.env) {
+    if (!telemetryEnabled(env))
+        return;
+    appendEvent({
+        event: "kibi_operation",
+        timestamp: new Date().toISOString(),
+        properties: {
+            ...baseProperties(source, env),
+            interface: operation.interface,
+            operation: operation.operation,
+            status: operation.status,
+            duration_ms: Math.max(0, Math.round(operation.durationMs)),
+            error_category: telemetryCategory(operation.errorCategory),
+            exit_code: operation.exitCode ?? null,
+        },
+    }, env);
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+export function recordHookTelemetry(source, hook, env = process.env) {
+    if (!telemetryEnabled(env))
+        return;
+    appendEvent({
+        event: "kibi_hook",
+        timestamp: new Date().toISOString(),
+        properties: {
+            ...baseProperties(source, env),
+            hook_event: hook.hookEvent,
+            hook_action: hook.hookAction,
+            path_kind: hook.pathKind ?? null,
+            kb_operation: hook.kbOperation ?? null,
+            kb_used_before: hook.kbUsedBefore ?? null,
+            requirement_count: hook.requirementCount ?? null,
+        },
+    }, env);
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+export function clearTelemetryQueue(env = process.env) {
+    const directory = telemetryDirectory(env);
+    let names;
+    try {
+        names = fs.readdirSync(directory);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (name === QUEUE_FILE ||
+            name === SESSIONS_FILE ||
+            name.endsWith(SENDING_SUFFIX)) {
+            fs.rmSync(path.join(directory, name), { force: true });
+        }
+    }
+}
+function parseQueued(text, now) {
+    const events = [];
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const event = JSON.parse(line);
+            const age = now - Date.parse(event.timestamp);
+            if (Number.isFinite(age) && age <= MAX_EVENT_AGE_MS)
+                events.push(event);
+        }
+        catch {
+            // A torn line from a crashed writer is dropped.
+        }
+    }
+    return events;
+}
+function flushDue(file, now) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const lines = text.split("\n").filter((line) => line.trim() !== "");
+    if (lines.length === 0)
+        return false;
+    if (lines.length >= FLUSH_BATCH_EVENTS)
+        return true;
+    try {
+        const first = JSON.parse(lines[0] ?? "");
+        return now - Date.parse(first.timestamp) >= FLUSH_MAX_AGE_MS;
+    }
+    catch {
+        return true;
+    }
+}
+/** Atomically take the queue and any batch a dead process left behind. */
+function claimBatches(directory, now) {
+    const claimed = [];
+    let names;
+    try {
+        names = fs.readdirSync(directory);
+    }
+    catch {
+        return claimed;
+    }
+    for (const name of names) {
+        if (!name.endsWith(SENDING_SUFFIX))
+            continue;
+        const file = path.join(directory, name);
+        try {
+            if (now - fs.statSync(file).mtimeMs < STALE_CLAIM_MS)
+                continue;
+            const reclaimed = `${file}.${randomUUID()}${SENDING_SUFFIX}`;
+            fs.renameSync(file, reclaimed);
+            claimed.push(reclaimed);
+        }
+        catch {
+            // Another process reclaimed it first.
+        }
+    }
+    const queue = path.join(directory, QUEUE_FILE);
+    const target = path.join(directory, `${QUEUE_FILE}.${process.pid}.${randomUUID()}${SENDING_SUFFIX}`);
+    try {
+        fs.renameSync(queue, target);
+        claimed.push(target);
+    }
+    catch {
+        // Nothing queued, or another process is sending it.
+    }
+    return claimed;
+}
+// implements REQ-kibi-anonymous-usage-telemetry
+/**
+ * Send queued events in one batch when a flush is due (or forced). Returns
+ * the number of events sent. A failed send puts the events back for the next
+ * flush; nothing here throws.
+ */
+export async function flushTelemetry(options = {}, env = process.env) {
+    if (!telemetryEnabled(env))
+        return 0;
+    const directory = telemetryDirectory(env);
+    const now = Date.now();
+    if (!options.force && !flushDue(queuePath(env), now))
+        return 0;
+    const claimed = claimBatches(directory, now);
+    if (claimed.length === 0)
+        return 0;
+    const events = [];
+    for (const file of claimed) {
+        try {
+            events.push(...parseQueued(fs.readFileSync(file, "utf8"), now));
+        }
+        catch {
+            // Unreadable batch: drop it.
+        }
+    }
+    const release = () => {
+        for (const file of claimed)
+            fs.rmSync(file, { force: true });
+    };
+    if (events.length === 0) {
+        release();
+        return 0;
+    }
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_FLUSH_TIMEOUT_MS);
+    timer.unref?.();
+    try {
+        const response = await fetchImpl(`${telemetryHost(env)}/batch/`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                api_key: telemetryKey(env),
+                historical_migration: false,
+                batch: events,
+            }),
+            signal: controller.signal,
+        });
+        // A 4xx means PostHog will never accept this batch; drop it.
+        if (!response.ok && response.status >= 500)
+            throw new Error("retry");
+        release();
+        return response.ok ? events.length : 0;
+    }
+    catch {
+        release();
+        for (const event of events)
+            appendEvent(event, env);
+        return 0;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-agent-core",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,6 +34,10 @@
       "types": "./dist/requirement-candidates.d.ts",
       "default": "./dist/requirement-candidates.js"
     },
+    "./usage-telemetry": {
+      "types": "./dist/usage-telemetry.d.ts",
+      "default": "./dist/usage-telemetry.js"
+    },
     "./snippets": {
       "types": "./dist/snippets.d.ts",
       "default": "./dist/snippets.js"