getpatter 0.6.4 → 0.6.6

package/dist/cli.js

@@ -785,9 +785,9 @@ function loadDashboardHtml() {
     (0, import_node_path.join)(here, "dashboard", "ui.html"),
     (0, import_node_path.join)(here, "..", "dashboard", "ui.html")
   ];
-  for (const path3 of candidates) {
+  for (const path4 of candidates) {
     try {
-      return (0, import_node_fs.readFileSync)(path3, "utf8");
+      return (0, import_node_fs.readFileSync)(path4, "utf8");
     } catch {
     }
   }
@@ -987,7 +987,470 @@ function showBanner() {
   console.log("\n" + BANNER);
 }
 
+// src/telemetry/env.ts
+var CI_ENV_VARS = [
+  "CI",
+  "CONTINUOUS_INTEGRATION",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "TRAVIS",
+  "CIRCLECI",
+  "APPVEYOR",
+  "TF_BUILD",
+  "TEAMCITY_VERSION",
+  "BUILDKITE",
+  "DRONE",
+  "JENKINS_URL",
+  "HUDSON_URL",
+  "BAMBOO_BUILDKEY",
+  "CODEBUILD_BUILD_ID"
+];
+var TEST_ENV_VARS = ["VITEST", "JEST_WORKER_ID"];
+function isTruthy(value) {
+  if (value === void 0) return false;
+  const v = value.trim().toLowerCase();
+  return v !== "" && v !== "0" && v !== "false" && v !== "no" && v !== "off";
+}
+function isCi() {
+  return CI_ENV_VARS.some((name) => isTruthy(process.env[name]));
+}
+function isTest() {
+  if (TEST_ENV_VARS.some((name) => process.env[name] !== void 0)) return true;
+  const node = (process.env.NODE_ENV ?? "").trim().toLowerCase();
+  const patter = (process.env.PATTER_ENV ?? "").trim().toLowerCase();
+  return node === "test" || patter === "test";
+}
+
+// src/telemetry/install-id.ts
+var import_node_crypto2 = require("crypto");
+var fs3 = __toESM(require("fs"));
+var os = __toESM(require("os"));
+var path3 = __toESM(require("path"));
+var RUN_ID = (0, import_node_crypto2.randomUUID)().replace(/-/g, "");
+var HEX32 = /^[0-9a-f]{32}$/;
+var cachedInstallId = null;
+function runId() {
+  return RUN_ID;
+}
+function statePath() {
+  const base = process.env.PATTER_TELEMETRY_STATE_DIR || process.env.XDG_STATE_HOME;
+  const root = base && base.length > 0 ? base : path3.join(os.homedir(), ".getpatter");
+  return path3.join(root, "install-id");
+}
+function installId() {
+  if (cachedInstallId !== null) return cachedInstallId;
+  const p = statePath();
+  try {
+    const existing = fs3.readFileSync(p, "utf8").trim();
+    if (HEX32.test(existing)) {
+      cachedInstallId = existing;
+      return cachedInstallId;
+    }
+  } catch {
+  }
+  const newId = (0, import_node_crypto2.randomUUID)().replace(/-/g, "");
+  try {
+    fs3.mkdirSync(path3.dirname(p), { recursive: true });
+    fs3.writeFileSync(p, newId, "utf8");
+    cachedInstallId = newId;
+  } catch {
+    cachedInstallId = RUN_ID;
+  }
+  return cachedInstallId;
+}
+function optOutPath() {
+  return path3.join(path3.dirname(statePath()), "telemetry-disabled");
+}
+function isOptedOut() {
+  try {
+    return fs3.existsSync(optOutPath());
+  } catch {
+    return false;
+  }
+}
+function setOptOut(disabled) {
+  const p = optOutPath();
+  if (disabled) {
+    fs3.mkdirSync(path3.dirname(p), { recursive: true });
+    fs3.writeFileSync(p, "1", "utf8");
+  } else {
+    try {
+      fs3.unlinkSync(p);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
+}
+
+// src/telemetry/consent.ts
+function isEnabled(flag) {
+  if (isTruthy(process.env.DO_NOT_TRACK)) return false;
+  if (isTruthy(process.env.PATTER_TELEMETRY_DISABLED)) return false;
+  if (isOptedOut()) return false;
+  if (flag === false) return false;
+  if (isCi() || isTest()) return false;
+  return true;
+}
+
+// src/telemetry/events.ts
+var os2 = __toESM(require("os"));
+
+// src/telemetry/stack.ts
+var STACK_VENDORS = /* @__PURE__ */ new Set([
+  "openai",
+  "anthropic",
+  "google",
+  "cerebras",
+  "groq",
+  "deepgram",
+  "elevenlabs",
+  "cartesia",
+  "whisper",
+  "soniox",
+  "assemblyai",
+  "speechmatics",
+  "lmnt",
+  "rime",
+  "inworld",
+  "telnyx",
+  "other"
+]);
+
+// src/telemetry/events.ts
+var SCHEMA_VERSION = 5;
+var EVENT_SDK_INITIALIZED = "sdk_initialized";
+var EVENT_FIRST_RUN = "first_run";
+var EVENT_CLI_COMMAND = "cli_command";
+var EVENT_FEATURE_USED = "feature_used";
+var EVENT_AGENT_CONFIGURED = "agent_configured";
+var EVENT_CALL_STARTED = "call_started";
+var EVENT_CALL_COMPLETED = "call_completed";
+var ALLOWED_EVENTS = /* @__PURE__ */ new Set([
+  EVENT_SDK_INITIALIZED,
+  EVENT_FIRST_RUN,
+  EVENT_CLI_COMMAND,
+  EVENT_FEATURE_USED,
+  EVENT_AGENT_CONFIGURED,
+  EVENT_CALL_STARTED,
+  EVENT_CALL_COMPLETED
+]);
+var DIMENSION_VALUES = {
+  carrier: /* @__PURE__ */ new Set(["twilio", "telnyx", "plivo", "none"]),
+  tunnel: /* @__PURE__ */ new Set(["static", "configured", "none"]),
+  engine: /* @__PURE__ */ new Set(["realtime", "convai", "pipeline"]),
+  provider: /* @__PURE__ */ new Set([
+    "openai",
+    "elevenlabs",
+    "deepgram",
+    "cartesia",
+    "cerebras",
+    "anthropic",
+    "google",
+    "whisper",
+    "other"
+  ]),
+  // agent_configured dimensions
+  custom_tool_count_bucket: /* @__PURE__ */ new Set(["0", "1", "2_3", "4_6", "7_12", "13_plus"]),
+  integration: /* @__PURE__ */ new Set(["openclaw", "mcp", "hermes", "other", "none"]),
+  integration_kind: /* @__PURE__ */ new Set(["consult", "mcp", "none"]),
+  mcp_server_count_bucket: /* @__PURE__ */ new Set(["0", "1", "2_3", "4_plus"]),
+  // call_started / call_completed: inbound vs outbound — a core usage split.
+  direction: /* @__PURE__ */ new Set(["inbound", "outbound", "none"]),
+  // cli_command: which CLI subcommand was invoked (never args/flags values).
+  cli_command: /* @__PURE__ */ new Set(["dashboard", "eval", "telemetry", "none", "other"]),
+  // call_completed: the call's terminal outcome
+  outcome: /* @__PURE__ */ new Set(["completed", "error", "no_answer", "busy", "failed"]),
+  // call_completed: terminal error code (mirrors ErrorCode, plus "other"). Never
+  // the error message.
+  error_code: /* @__PURE__ */ new Set([
+    "config",
+    "connection",
+    "auth",
+    "timeout",
+    "rate_limit",
+    "webhook_verification",
+    "input_validation",
+    "provider_error",
+    "provision",
+    "internal",
+    "other"
+  ]),
+  // feature_used (pipeline): per-layer vendor of the composed stack. A
+  // providerKey not on the closed allowlist collapses to "other"; an absent layer
+  // is omitted (the value set keeps "none" only as a safety token).
+  stt_provider: /* @__PURE__ */ new Set([...STACK_VENDORS, "none"]),
+  tts_provider: /* @__PURE__ */ new Set([...STACK_VENDORS, "none"]),
+  llm_provider: /* @__PURE__ */ new Set([...STACK_VENDORS, "none"]),
+  // sdk_initialized: anonymous deploy-shape (presence-only env/file probes).
+  invoked_by_agent: /* @__PURE__ */ new Set(["claude", "cursor", "copilot", "gemini", "windsurf", "other", "none"]),
+  serverless: /* @__PURE__ */ new Set(["lambda", "cloud_run", "vercel", "azure_functions", "none"]),
+  cloud: /* @__PURE__ */ new Set(["aws", "gcp", "azure", "fly", "none"]),
+  package_manager: /* @__PURE__ */ new Set(["npm", "pnpm", "yarn", "bun", "pip", "uv", "poetry", "pipenv", "conda", "none"]),
+  days_since_install_bucket: /* @__PURE__ */ new Set(["0", "1_7", "8_30", "30_plus"]),
+  // agent_configured: feature-adoption (Realtime tuning).
+  noise_reduction: /* @__PURE__ */ new Set(["near_field", "far_field", "none"]),
+  turn_detection: /* @__PURE__ */ new Set(["default", "custom", "none"]),
+  // call_completed: how many conversational turns the call had.
+  turn_count_bucket: /* @__PURE__ */ new Set(["0", "1", "2_3", "4_6", "7_12", "13_plus"])
+};
+var NUMERIC_DIMENSIONS = /* @__PURE__ */ new Set([
+  "builtin_tool_count",
+  "latency_ms",
+  "duration_seconds",
+  "cost_usd"
+]);
+var STRING_DIMENSIONS = /* @__PURE__ */ new Set([
+  "stt_model",
+  "tts_model",
+  "llm_model",
+  "previous_sdk_version"
+]);
+var MODEL_TOKEN_RE = /^[a-z0-9][a-z0-9.-]{0,40}$/;
+var BOOL_DIMENSIONS = /* @__PURE__ */ new Set([
+  "container",
+  "preambles_used",
+  "per_tool_timeouts_set",
+  "llm_fallback_configured"
+]);
+var ALLOWED_DIMENSIONS = /* @__PURE__ */ new Set([
+  ...Object.keys(DIMENSION_VALUES),
+  ...NUMERIC_DIMENSIONS,
+  ...STRING_DIMENSIONS,
+  ...BOOL_DIMENSIONS
+]);
+function osFamily() {
+  const p = os2.platform();
+  if (p === "win32") return "windows";
+  return p || "unknown";
+}
+function arch2() {
+  const a = os2.arch();
+  if (a === "x64") return "x86_64";
+  if (a === "arm64") return "arm64";
+  return "other";
+}
+function runtimeVersion() {
+  const parts = (process.versions.node ?? "0.0").split(".");
+  return `${parts[0] ?? "0"}.${parts[1] ?? "0"}`;
+}
+function buildEvent(name, opts) {
+  if (!ALLOWED_EVENTS.has(name)) {
+    throw new Error(`unknown telemetry event: ${name}`);
+  }
+  const event = {
+    event: name,
+    schema_version: SCHEMA_VERSION,
+    run_id: runId(),
+    install_id: installId(),
+    sdk: "typescript",
+    sdk_version: opts.sdkVersion,
+    os: osFamily(),
+    arch: arch2(),
+    runtime: "node",
+    runtime_version: runtimeVersion(),
+    ci: isCi() || isTest()
+  };
+  for (const [key, raw] of Object.entries(opts.dimensions ?? {})) {
+    if (!ALLOWED_DIMENSIONS.has(key) || raw === null || raw === void 0) {
+      continue;
+    }
+    let value = raw;
+    const allowed = DIMENSION_VALUES[key];
+    if (allowed && !(typeof value === "string" && allowed.has(value))) {
+      value = "other";
+    } else if (STRING_DIMENSIONS.has(key)) {
+      if (!(typeof value === "string" && MODEL_TOKEN_RE.test(value))) {
+        continue;
+      }
+    } else if (BOOL_DIMENSIONS.has(key) && typeof value !== "boolean") {
+      continue;
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      event[key] = value;
+    }
+  }
+  return event;
+}
+
+// src/telemetry/client.ts
+var DEFAULT_ENDPOINT = "https://telemetry.getpatter.com/v1/ingest";
+var TIMEOUT_MS = 3e3;
+var BUFFER_MAX = 256;
+var noticeShown = false;
+var liveClients = /* @__PURE__ */ new Set();
+var exitHookRegistered = false;
+function showNoticeOnce() {
+  if (noticeShown) return;
+  noticeShown = true;
+  getLogger().info(
+    "Anonymous usage telemetry is on (no PII, no call content). Collected: a random anonymous install id, SDK version, language, OS family, runtime version, coarse feature flags, the composed stack (provider + model per layer), tool counts, integration category, and per-call duration, latency, cost, and error codes (no call content, no message text). Disable with PATTER_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1, or telemetry: false. Details: https://docs.getpatter.com/telemetry"
+  );
+}
+function registerExitHook() {
+  if (exitHookRegistered) return;
+  exitHookRegistered = true;
+  process.once("beforeExit", () => {
+    for (const ref of [...liveClients]) {
+      const client = ref.deref();
+      if (client) void client.close();
+      else liveClients.delete(ref);
+    }
+  });
+}
+var TelemetryClient = class {
+  sdkVersion;
+  enabledFlag;
+  endpoint;
+  debug;
+  buffer = [];
+  flushing = false;
+  closed = false;
+  selfRef = new WeakRef(this);
+  constructor(options) {
+    this.sdkVersion = options.sdkVersion;
+    this.enabledFlag = isEnabled(options.flag);
+    this.endpoint = options.endpoint ?? process.env.PATTER_TELEMETRY_ENDPOINT ?? DEFAULT_ENDPOINT;
+    this.debug = isTruthy(process.env.PATTER_TELEMETRY_DEBUG);
+    if (this.enabledFlag && !this.debug) {
+      showNoticeOnce();
+      registerExitHook();
+      liveClients.add(this.selfRef);
+    }
+  }
+  get enabled() {
+    return this.enabledFlag;
+  }
+  /** Enqueue an event. Fire-and-forget; never throws, never blocks. */
+  record(name, dimensions) {
+    if (!this.enabledFlag || this.closed) return;
+    let event;
+    try {
+      event = buildEvent(name, { sdkVersion: this.sdkVersion, dimensions });
+    } catch (err) {
+      getLogger().debug("telemetry buildEvent failed", err);
+      return;
+    }
+    if (this.debug) {
+      try {
+        process.stderr.write(`[patter telemetry] ${JSON.stringify(event)}
+`);
+      } catch {
+      }
+      return;
+    }
+    try {
+      if (this.buffer.length >= BUFFER_MAX) this.buffer.shift();
+      this.buffer.push(event);
+      this.scheduleFlush();
+    } catch (err) {
+      getLogger().debug("telemetry enqueue failed", err);
+    }
+  }
+  /**
+   * Schedule a flush of any buffered events. Events recorded before the server
+   * is running (e.g. at `new Patter(...)`) sit in the buffer; call this once the
+   * server is up so they ship promptly. Cheap when disabled or buffer is empty.
+   */
+  flushPending() {
+    if (!this.enabledFlag || this.debug) return;
+    try {
+      this.scheduleFlush();
+    } catch (err) {
+      getLogger().debug("telemetry flushPending failed", err);
+    }
+  }
+  /** Flush remaining events (graceful shutdown). Never throws. */
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    liveClients.delete(this.selfRef);
+    if (!this.enabledFlag || this.debug) return;
+    try {
+      await this.flush();
+    } catch (err) {
+      getLogger().debug("telemetry close flush failed", err);
+    }
+  }
+  scheduleFlush() {
+    if (this.flushing) return;
+    this.flushing = true;
+    void this.flush().finally(() => {
+      this.flushing = false;
+    });
+  }
+  async flush() {
+    if (this.buffer.length === 0) return;
+    const events = this.buffer.splice(0, this.buffer.length);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    timer.unref?.();
+    try {
+      await fetch(this.endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(events),
+        signal: controller.signal
+      });
+    } catch (err) {
+      getLogger().debug("telemetry flush failed", err);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+
 // src/cli.ts
+async function emitCliCommand(command) {
+  try {
+    const client = new TelemetryClient({ sdkVersion: VERSION });
+    client.record("cli_command", { cli_command: command });
+    const timeout = new Promise((resolve2) => {
+      const t = setTimeout(resolve2, 600);
+      t.unref?.();
+    });
+    await Promise.race([client.close(), timeout]);
+  } catch {
+  }
+}
+function runTelemetryCommand(action) {
+  const act = action ?? "status";
+  if (act === "disable") {
+    try {
+      setOptOut(true);
+    } catch (err) {
+      console.log(`Could not write the opt-out marker: ${String(err)}`);
+      return 1;
+    }
+    console.log("Anonymous telemetry disabled. No usage data will be sent.");
+    return 0;
+  }
+  if (act === "enable") {
+    try {
+      setOptOut(false);
+    } catch (err) {
+      console.log(`Could not remove the opt-out marker: ${String(err)}`);
+      return 1;
+    }
+    console.log("Anonymous telemetry re-enabled (opt-out model, on by default).");
+    return 0;
+  }
+  if (act !== "status") {
+    console.log("Usage: getpatter telemetry [status|disable|enable]");
+    return 1;
+  }
+  const endpoint = process.env.PATTER_TELEMETRY_ENDPOINT || DEFAULT_ENDPOINT;
+  console.log(`Anonymous usage telemetry: ${isEnabled() ? "ENABLED" : "DISABLED"}`);
+  if (isOptedOut()) {
+    console.log("  Opted out via: getpatter telemetry disable (persisted marker)");
+  }
+  console.log(`  Endpoint: ${endpoint}`);
+  console.log("  Inspect what would be sent (prints, sends nothing): PATTER_TELEMETRY_DEBUG=1");
+  console.log(
+    "  Disable: getpatter telemetry disable  |  DO_NOT_TRACK=1  |  PATTER_TELEMETRY_DISABLED=1"
+  );
+  console.log("  Details: https://docs.getpatter.com/telemetry");
+  return 0;
+}
 function parseArgs(argv) {
   const args = argv.slice(2);
   let port = 8e3;
@@ -1008,17 +1471,44 @@ function printEvalStub() {
     "Evaluations are not yet available in the TypeScript SDK.\nUse the Python SDK instead:\n\n  pip install getpatter\n  patter eval --help\n\nSee https://github.com/PatterAI/Patter for docs."
   );
 }
+function printHermesStub() {
+  console.log(
+    "The Hermes wizard (doctor / setup / test / trace / diagnose /\nattach-number) lives in the Python CLI today. Use it from the Python SDK:\n\n  pip install getpatter\n  patter hermes doctor\n  patter hermes setup\n  patter hermes test\n\nThe HermesLLM provider itself is fully available in this TypeScript SDK\n(import { HermesLLM } from 'getpatter'). See\nhttps://docs.getpatter.com/integrations/hermes for docs."
+  );
+}
+function printOpenClawStub() {
+  console.log(
+    "The OpenClaw wizard (doctor / setup / test / call / agents /\nattach-number) lives in the Python CLI today. Use it from the Python SDK:\n\n  pip install getpatter\n  patter openclaw setup --enable-openclaw --agent receptionist  # inbound\n  patter openclaw setup --mode outbound --agent sales           # outbound\n  patter openclaw doctor\n\nThe OpenClawLLM provider itself is fully available in this TypeScript SDK\n(import { OpenClawLLM } from 'getpatter'). See\nhttps://docs.getpatter.com/integrations/openclaw for docs."
+  );
+}
 async function main() {
   const command = process.argv[2];
+  if (command === "telemetry") {
+    process.exit(runTelemetryCommand(process.argv[3]));
+  }
   if (command === "eval") {
+    await emitCliCommand("eval");
     printEvalStub();
     process.exit(0);
   }
+  if (command === "hermes") {
+    printHermesStub();
+    process.exit(0);
+  }
+  if (command === "openclaw") {
+    printOpenClawStub();
+    process.exit(0);
+  }
   if (command !== "dashboard") {
+    await emitCliCommand(command ? "other" : "none");
     console.log("Usage: getpatter dashboard [--port 8000]");
     console.log("       getpatter eval          (stub \u2014 use Python SDK for evals)");
+    console.log("       getpatter hermes        (stub \u2014 use Python SDK for the wizard)");
+    console.log("       getpatter openclaw      (stub \u2014 use Python SDK for the wizard)");
+    console.log("       getpatter telemetry [status|disable|enable]");
     process.exit(command ? 1 : 0);
   }
+  await emitCliCommand("dashboard");
   const { port } = parseArgs(process.argv);
   showBanner();
   const store = new MetricsStore();