kibi-agent-core 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # kibi-agent-core
 
+## 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
+
+- 45036a3: Signoff guidance no longer tells agents to attach `latest.html` as a file. Chat apps (the Claude apps, Slack and most others) show an attached HTML file as raw source or a download, so agents now share the page only as a rendered page, such as a Claude Artifact, and otherwise leave the message text as the whole view. Updates the kibi-decisions and kibi-commit-review skills (1.2.1), the `kibi signoff` page note and the stop-hook reminder.
+
 ## 0.9.0
 
 ### Minor 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, and attach or publish `.kb/briefs/signoff/latest.html` when the host can show a page (kibi-decisions, resources/signoff-views.md).",
+        "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).",
     ].join("\n");
 }
 function readSettled(file) {

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,107 @@
+/**
+ * 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 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;
+};
+/** 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"];
+/** 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;
+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,473 @@
+// 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 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 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
+/** 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 (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 baseProperties(source, env) {
+    const sessionId = source.sessionId?.trim();
+    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() || "unknown",
+        session: sessionId ? hashTelemetryId(sessionId) : null,
+        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
+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: operation.errorCategory ?? null,
+            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.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.0",
+  "version": "0.10.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"