@ycodium-ai/plugin-telemetry 0.2.0

package/README.md

@@ -0,0 +1,42 @@
+# @ycodium-ai/plugin-telemetry
+
+Sends anonymous counts of which Ycodium features get used. No code, no
+prompts, no file names.
+
+## What it does
+
+The host forwards usage events into the `record` command. This plugin batches
+them and posts to PostHog. The endpoint and project key come from the entry
+config, which the host fills from `YCODIUM_POSTHOG_KEY` and
+`YCODIUM_POSTHOG_HOST`.
+
+Identity is a SHA-256 of a Codex account id, else a Claude user id, else a
+one-time anonymous id stored in the plugin data directory. If none of those
+can be read, nothing is sent.
+
+`YCODIUM_TELEMETRY_ENABLED=false` disables the bundle entry before the plugin
+loads. Turning the row off in Settings → Plugins does the same thing.
+
+## Install
+
+```
+ycodium plugin add @ycodium-ai/plugin-telemetry
+```
+
+The plugin asks to read the identity files the host injects at assembly
+(`config:telemetryIdentityPaths`). Those paths are listed on the plugin row
+under Declared permissions.
+
+Ycodium ships it enabled as `core.telemetry`. Disabling it stops collection.
+Uninstalling it writes a removal to the home patch so a restart does not bring
+it back.
+
+## Developing
+
+Built from the Ycodium repository. The Node entry is bundled, but
+`@ycodium-ai/plugin-api` stays external and is provided by the Ycodium host at
+load time.
+
+## License
+
+UNLICENSED.

package/dist/index.js

@@ -0,0 +1,336 @@
+// src/index.ts
+import * as NodeProcess from "node:process";
+import { definePlugin } from "@ycodium-ai/plugin-api";
+
+// src/identity.ts
+import * as NodeCrypto from "node:crypto";
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+var ANONYMOUS_ID_FILENAME = "anonymous-id";
+var sha256Hex = (value) => NodeCrypto.createHash("sha256").update(value, "utf8").digest("hex");
+var readJsonString = async (fs, path, pick) => {
+  if (path === null) return null;
+  let text;
+  try {
+    text = await fs.readFile(path);
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+  const picked = pick(parsed);
+  return typeof picked === "string" && picked.trim().length > 0 ? picked : null;
+};
+var codexAccountId = (fs, path) => readJsonString(fs, path, (root) => {
+  const tokens = root["tokens"];
+  return typeof tokens === "object" && tokens !== null ? tokens["account_id"] : void 0;
+});
+var claudeUserId = (fs, path) => readJsonString(fs, path, (root) => root["userID"]);
+var anonymousId = async (fs, dataDir, legacyPath) => {
+  const ownPath = NodePath.join(dataDir, ANONYMOUS_ID_FILENAME);
+  try {
+    const existing = NodeFS.readFileSync(ownPath, "utf8").trim();
+    if (existing.length > 0) return existing;
+  } catch {
+  }
+  let value = null;
+  if (legacyPath !== null) {
+    try {
+      const legacy = (await fs.readFile(legacyPath)).trim();
+      if (legacy.length > 0) value = legacy;
+    } catch {
+    }
+  }
+  value ??= NodeCrypto.randomUUID();
+  try {
+    NodeFS.mkdirSync(dataDir, { recursive: true });
+    NodeFS.writeFileSync(ownPath, value, "utf8");
+  } catch {
+  }
+  return value;
+};
+var resolveTelemetryIdentity = async (fs, paths, dataDir) => {
+  const codex = await codexAccountId(fs, paths.codexAuthPath);
+  if (codex !== null) return { source: "codex", distinctId: sha256Hex(codex) };
+  const claude = await claudeUserId(fs, paths.claudeConfigPath);
+  if (claude !== null) return { source: "claude", distinctId: sha256Hex(claude) };
+  if (dataDir.trim().length === 0) return null;
+  const anonymous = await anonymousId(fs, dataDir, paths.legacyAnonymousIdPath);
+  return { source: "anonymous", distinctId: sha256Hex(anonymous) };
+};
+
+// src/sender.ts
+var DEFAULT_BATCH_SIZE = 20;
+var DEFAULT_MAX_BUFFERED_EVENTS = 1e3;
+var FLUSH_INTERVAL_MILLIS = 1e3;
+var MAX_FLUSH_INTERVAL_MILLIS = 3e5;
+var flushIntervalMillis = (consecutiveFailures) => consecutiveFailures <= 0 ? FLUSH_INTERVAL_MILLIS : Math.min(FLUSH_INTERVAL_MILLIS * 2 ** consecutiveFailures, MAX_FLUSH_INTERVAL_MILLIS);
+var shouldReportFlushFailure = (consecutiveFailures) => (consecutiveFailures & consecutiveFailures - 1) === 0;
+var TelemetrySender = class {
+  #queue = [];
+  #consecutiveFailures = 0;
+  #timer = null;
+  #stopped = false;
+  #options;
+  #batchSize;
+  #maxBuffered;
+  constructor(options) {
+    this.#options = options;
+    this.#batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    this.#maxBuffered = options.maxBufferedEvents ?? DEFAULT_MAX_BUFFERED_EVENTS;
+  }
+  /** 队列当前长度。测试用。 */
+  get pending() {
+    return this.#queue.length;
+  }
+  start() {
+    this.#schedule();
+  }
+  /** 队列满了丢最老的：新事件比旧事件有用,而无界队列是宿主的性能红线。 */
+  record(event) {
+    if (this.#stopped) return;
+    this.#queue.push(event);
+    if (this.#queue.length > this.#maxBuffered) {
+      const dropped = this.#queue.length - this.#maxBuffered;
+      this.#queue.splice(0, dropped);
+      this.#options.log.warn("telemetry buffer full; dropped oldest events", {
+        dropped,
+        event: event.event
+      });
+    }
+  }
+  async stop() {
+    this.#stopped = true;
+    if (this.#timer !== null) {
+      clearTimeout(this.#timer);
+      this.#timer = null;
+    }
+    await this.flush();
+  }
+  /** 一直发到队列空或者某一批失败为止。 */
+  async flush() {
+    while (this.#queue.length > 0) {
+      const batch = this.#queue.slice(0, this.#batchSize);
+      try {
+        await this.#send(batch);
+      } catch (cause) {
+        this.#onFailure(cause);
+        return;
+      }
+      this.#queue.splice(0, batch.length);
+      if (this.#consecutiveFailures > 0) {
+        this.#options.log.info("telemetry flush recovered", {
+          afterConsecutiveFailures: this.#consecutiveFailures
+        });
+        this.#consecutiveFailures = 0;
+      }
+    }
+  }
+  #onFailure(cause) {
+    this.#consecutiveFailures += 1;
+    if (!shouldReportFlushFailure(this.#consecutiveFailures)) return;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (this.#consecutiveFailures === 1) {
+      this.#options.log.error("failed to flush telemetry", { cause: message });
+      return;
+    }
+    this.#options.log.warn("telemetry is still failing to flush", {
+      consecutiveFailures: this.#consecutiveFailures,
+      nextAttemptInMillis: flushIntervalMillis(this.#consecutiveFailures)
+    });
+  }
+  async #send(batch) {
+    const response = await this.#options.fetch(`${this.#options.endpoint}/batch/`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        api_key: this.#options.apiKey,
+        batch: batch.map((entry) => ({
+          event: entry.event,
+          distinct_id: this.#options.distinctId,
+          properties: {
+            ...entry.properties,
+            ...this.#options.baseProperties,
+            // 不给这个 distinct_id 建 person profile:我们只数事件,不画像。
+            $process_person_profile: false
+          },
+          timestamp: entry.capturedAt
+        }))
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`telemetry endpoint returned ${response.status}`);
+    }
+  }
+  /** 每轮重算间隔：失败越久等得越长,恢复后立刻回到一秒一次。 */
+  #schedule() {
+    if (this.#stopped) return;
+    this.#timer = setTimeout(() => {
+      void this.flush().finally(() => this.#schedule());
+    }, flushIntervalMillis(this.#consecutiveFailures));
+    this.#timer.unref?.();
+  }
+};
+
+// src/index.ts
+var RECORD_PAYLOAD_SCHEMA = {
+  type: "object",
+  properties: {
+    event: { type: "string" },
+    properties: { type: "object" }
+  },
+  required: ["event"],
+  additionalProperties: false
+};
+var EMPTY_PAYLOAD_SCHEMA = {
+  type: "object",
+  properties: {},
+  additionalProperties: false
+};
+var stringField = (value, key) => {
+  if (typeof value !== "object" || value === null) return null;
+  const picked = value[key];
+  return typeof picked === "string" && picked.trim().length > 0 ? picked : null;
+};
+var objectField = (value, key) => {
+  if (typeof value !== "object" || value === null) return void 0;
+  const picked = value[key];
+  return typeof picked === "object" && picked !== null && !Array.isArray(picked) ? picked : void 0;
+};
+var identityPathsOf = (config) => ({
+  codexAuthPath: config.codexAuthPath ?? null,
+  claudeConfigPath: config.claudeConfigPath ?? null,
+  legacyAnonymousIdPath: config.legacyAnonymousIdPath ?? null
+});
+var baseProperties = (config) => {
+  const wsl = NodeProcess.env["WSL_DISTRO_NAME"]?.trim();
+  return {
+    platform: NodeProcess.platform,
+    arch: NodeProcess.arch,
+    ...wsl !== void 0 && wsl.length > 0 ? { wsl } : {},
+    ...config.appVersion !== void 0 ? { ycodiumCodeVersion: config.appVersion } : {},
+    ...config.clientType !== void 0 ? { clientType: config.clientType } : {}
+  };
+};
+var TelemetryRuntime = class {
+  #sender = null;
+  #pending = [];
+  #ready = false;
+  // 在飞的身份解析。stop 必须等它落完:那条路会往 dataDir 写文件,不等就会在宿主
+  // 已经开始删目录之后再把目录建回来。
+  #starting = null;
+  #ctx;
+  constructor(ctx) {
+    this.#ctx = ctx;
+  }
+  start() {
+    this.#starting = this.#initialize().catch((cause) => {
+      this.#ctx.log.error("telemetry could not start", {
+        cause: cause instanceof Error ? cause.message : String(cause)
+      });
+      this.#pending = [];
+      this.#ready = true;
+    });
+  }
+  async #initialize() {
+    const config = this.#ctx.config;
+    const apiKey = config.posthogKey?.trim();
+    const endpoint = config.posthogHost?.trim();
+    if (apiKey === void 0 || apiKey.length === 0 || endpoint === void 0) {
+      this.#ctx.log.warn("telemetry has no endpoint configured; not sending anything");
+      this.#pending = [];
+      this.#ready = true;
+      return;
+    }
+    const identity = await resolveTelemetryIdentity(
+      this.#ctx.fs,
+      identityPathsOf(config),
+      this.#ctx.paths.dataDir
+    );
+    if (identity === null) {
+      this.#ctx.log.warn("telemetry has no stable identifier; not sending anything");
+      this.#pending = [];
+      this.#ready = true;
+      return;
+    }
+    const sender = new TelemetrySender({
+      endpoint,
+      apiKey,
+      distinctId: identity.distinctId,
+      baseProperties: baseProperties(config),
+      // ctx.http 已按这台机器的全局默认代理解析过。裸 fetch 绕开代理,配了代理的机器
+      // 上会静默失败——搬迁前宿主用的就是裸 fetch,那些机器一条都没发出去。
+      fetch: this.#ctx.http,
+      log: this.#ctx.log
+    });
+    for (const event of this.#pending) sender.record(event);
+    this.#pending = [];
+    this.#sender = sender;
+    this.#ready = true;
+    sender.start();
+    this.#ctx.log.info("telemetry started", { identitySource: identity.source });
+  }
+  record(event, properties) {
+    const entry = {
+      event,
+      properties,
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (this.#sender !== null) {
+      this.#sender.record(entry);
+      return;
+    }
+    if (!this.#ready) this.#pending.push(entry);
+  }
+  flush() {
+    return this.#sender?.flush() ?? Promise.resolve();
+  }
+  async stop() {
+    await this.#starting;
+    this.#starting = null;
+    await this.#sender?.stop();
+    this.#sender = null;
+    this.#pending = [];
+  }
+};
+var index_default = definePlugin({
+  id: "telemetry",
+  apiVersion: 2,
+  activate: (ctx) => {
+    const runtime = new TelemetryRuntime(ctx);
+    runtime.start();
+    ctx.command({
+      name: "record",
+      description: "Records one anonymous usage event for batched delivery.",
+      // 宿主的薄壳按事件逐条转发,不是人点出来的动作。
+      scope: "read",
+      payloadSchema: RECORD_PAYLOAD_SCHEMA,
+      handle: (payload) => {
+        const event = stringField(payload, "event");
+        if (event === null) throw new Error("record requires a non-empty 'event'.");
+        runtime.record(event, objectField(payload, "properties"));
+        return Promise.resolve({ recorded: true });
+      }
+    });
+    ctx.command({
+      name: "flush",
+      description: "Sends everything currently queued, without waiting for the next interval.",
+      scope: "read",
+      payloadSchema: EMPTY_PAYLOAD_SCHEMA,
+      handle: async () => {
+        await runtime.flush();
+        return { flushed: true };
+      }
+    });
+    ctx.onDispose(() => runtime.stop());
+  }
+});
+export {
+  TelemetryRuntime,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@ycodium-ai/plugin-telemetry",
+  "version": "0.2.0",
+  "description": "Sends anonymous counts of which features get used. No code, no prompts.",
+  "keywords": [
+    "telemetry",
+    "ycodium",
+    "ycodium-plugin"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-beta.103",
+    "@types/node": "24.12.4",
+    "esbuild": "0.28.1",
+    "vite-plus": "0.2.2",
+    "@ycodium-ai/plugin-api": "0.1.1"
+  },
+  "ycodium": {
+    "plugin": "./dist/index.js",
+    "displayName": "Anonymous usage statistics",
+    "description": "Sends anonymous counts of which features get used. No code, no prompts.",
+    "icon": "chartColumn",
+    "permissions": [
+      {
+        "kind": "fs.read",
+        "paths": [
+          "config:telemetryIdentityPaths"
+        ]
+      }
+    ]
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsgo --noEmit",
+    "test": "vp test run"
+  }
+}