anyclaude-sdk 0.6.1 → 0.7.0

package/README.md

@@ -390,6 +390,10 @@ Runnable Vite projects in [`examples/`](examples/): **`browser-ide`** (WebContai
 | MCP / slash commands / background tasks / sub-agents | Built-in | Built-in |
 | Serverless survivor + prompt projection | — | Built-in |
 
+## Telemetry
+
+The SDK emits **anonymous, opt-out** usage telemetry (SDK version, runtime, a coarse model-family bucket, and which features are used) — never code, prompts, repo identity, paths, or keys, and a no-op unless you configure a collector. Disable with `ANYCLAUDE_TELEMETRY=0`, `DO_NOT_TRACK=1`, or `query({ disableTelemetry: true })`. Full disclosure: [TELEMETRY.md](TELEMETRY.md).
+
 ## License
 
 MIT

package/dist/agent.js

@@ -480,7 +480,12 @@ export async function* runAgent(options) {
                     yield {
                         type: 'system',
                         subtype: 'compact_boundary',
-                        compact_metadata: { trigger: 'manual', pre_tokens: 0 },
+                        compact_metadata: {
+                            trigger: 'manual',
+                            pre_tokens: 0,
+                            status: 'end',
+                            post_tokens: Math.round(estimateTokens(history)),
+                        },
                         uuid: uuid(),
                         session_id: sessionId,
                     };
@@ -581,21 +586,38 @@ export async function* runAgent(options) {
             if (options.autoCompact && autoCompactCount < 3 && history.length > 3) {
                 const limit = options.contextLimit ?? (contextWindowFor(resultModel) || 200_000);
                 const threshold = (options.compactThreshold ?? 0.8) * limit;
-                if (estimateTokens(history) > threshold) {
+                const preTokens = estimateTokens(history);
+                if (preTokens > threshold) {
                     await runHooks('PreCompact', { hook_event_name: 'PreCompact', trigger: 'auto' });
+                    // Emit a START boundary BEFORE the (possibly slow) summarization so a UI
+                    // can show a live "compacting…" indicator while the LLM call is in flight.
+                    yield {
+                        type: 'system',
+                        subtype: 'compact_boundary',
+                        compact_metadata: { trigger: 'auto', pre_tokens: Math.round(preTokens), status: 'start' },
+                        uuid: uuid(),
+                        session_id: sessionId,
+                    };
                     const compacted = await summarizeHistory(history, llm, { model, signal });
                     if (compacted) {
                         history.splice(0, history.length, ...compacted);
                         autoCompactCount++;
-                        yield {
-                            type: 'system',
-                            subtype: 'compact_boundary',
-                            compact_metadata: { trigger: 'auto', pre_tokens: Math.round(threshold) },
-                            uuid: uuid(),
-                            session_id: sessionId,
-                        };
-                        await runHooks('PostCompact', { hook_event_name: 'PostCompact', trigger: 'auto' });
                     }
+                    // END boundary closes the live indicator either way (compacted or not).
+                    yield {
+                        type: 'system',
+                        subtype: 'compact_boundary',
+                        compact_metadata: {
+                            trigger: 'auto',
+                            pre_tokens: Math.round(preTokens),
+                            status: 'end',
+                            post_tokens: Math.round(estimateTokens(history)),
+                        },
+                        uuid: uuid(),
+                        session_id: sessionId,
+                    };
+                    if (compacted)
+                        await runHooks('PostCompact', { hook_event_name: 'PostCompact', trigger: 'auto' });
                 }
             }
             let streamedText = '';

package/dist/index.d.ts

@@ -25,4 +25,5 @@ export { uuid } from './util/ids.js';
 export * as paths from './util/paths.js';
 export { priceFor, computeCostUSD, contextWindowFor, type Pricing } from './util/pricing.js';
 export { estimateTokens, summarizeHistory, compactWithWindow } from './compact.js';
+export { track, telemetryEnabled, detectRuntime, TELEMETRY_SDK_VERSION, type TelemetryOptions } from './telemetry.js';
 export { runToolLoop, type RunToolLoopOptions } from './loop.js';

package/dist/index.js

@@ -27,5 +27,6 @@ export { uuid } from './util/ids.js';
 export * as paths from './util/paths.js';
 export { priceFor, computeCostUSD, contextWindowFor } from './util/pricing.js';
 export { estimateTokens, summarizeHistory, compactWithWindow } from './compact.js';
+export { track, telemetryEnabled, detectRuntime, TELEMETRY_SDK_VERSION } from './telemetry.js';
 export { runToolLoop } from './loop.js';
 // (createResponsesClient is exported via ./llm/index.js)

package/dist/query.d.ts

@@ -5,6 +5,7 @@ import type { SlashCommand } from './commands/index.js';
 import type { SessionStoreLike } from './session/index.js';
 import type { MemoryStore } from './memory/index.js';
 import { type Workspace } from './agent.js';
+import { type TelemetryOptions } from './telemetry.js';
 export interface QueryOptions {
     /** A plain string (single turn) or a stream of user messages (multi-turn). */
     prompt: string | AsyncIterable<SDKUserMessage>;
@@ -109,6 +110,11 @@ export interface QueryOptions {
     settings?: boolean | import('./settings/index.js').Settings;
     /** Load `.claude/skills/*.md` as slash commands + a skill registry, or pass a Skill[]. */
     skills?: boolean | import('./skills/index.js').Skill[];
+    /** Anonymous, opt-out usage telemetry (version/runtime/which-features only — never
+     *  code, prompts, repo, or keys). Configure or disable via `telemetry`; see TELEMETRY.md. */
+    telemetry?: TelemetryOptions;
+    /** Convenience to force telemetry off for this run (same as `telemetry: { disabled: true }`). */
+    disableTelemetry?: boolean;
 }
 /** An async iterator of SDK messages, augmented with session controls. */
 export interface Query extends AsyncGenerator<SDKMessage, void, void> {

package/dist/query.js

@@ -3,6 +3,8 @@
 // Returns an AsyncGenerator<SDKMessage>. Accepts either a single string prompt
 // or an async iterable of SDKUserMessage (for multi-turn / interactive use).
 import { runAgent } from './agent.js';
+import { track, telemetryEnabled } from './telemetry.js';
+import { profileForModel } from './llm/profiles.js';
 export function query(options) {
     const prompt = typeof options.prompt === 'string'
         ? singlePrompt(options.prompt)
@@ -58,6 +60,29 @@ export function query(options) {
         skills: options.skills,
     });
     gen.interrupt = () => abortController.abort();
+    // Anonymous, aggregate adoption signal — one event per public run. Fire-and-forget,
+    // never blocks the generator, no-ops unless enabled + a collector is configured.
+    // Only booleans + a coarse model-family bucket leave the process (see telemetry.ts).
+    const telemetry = {
+        disabled: options.disableTelemetry,
+        ...options.telemetry,
+    };
+    if (telemetryEnabled(telemetry)) {
+        track('run', {
+            model_family: profileForModel(options.model).name,
+            client_workspace_tools: !!options.clientWorkspaceTools,
+            client_tools: !!options.clientTools?.length,
+            survivor: options.maxDurationMs != null,
+            mcp: !!options.mcpServers,
+            team: !!options.team,
+            background: !!options.background,
+            auto_compact: !!options.autoCompact,
+            skills: !!options.skills,
+            sessions: !!options.sessionStore,
+            partial_messages: !!options.includePartialMessages,
+            resumed: !!options.continueRun || !!options.resume,
+        }, telemetry);
+    }
     return gen;
 }
 /** Wrap a single text prompt into the async-iterable form runAgent expects. */

package/dist/telemetry.d.ts

@@ -0,0 +1,17 @@
+/** Bump on release so adoption can be bucketed by version. */
+export declare const TELEMETRY_SDK_VERSION = "0.7.0";
+export interface TelemetryOptions {
+    /** Force-disable for this call (highest precedence besides the global opt-outs). */
+    disabled?: boolean;
+    /** Collector URL. Defaults to `ANYCLAUDE_TELEMETRY_URL` then the built-in default. */
+    url?: string;
+}
+/** Resolve whether telemetry may run, honoring every documented opt-out. */
+export declare function telemetryEnabled(opts?: TelemetryOptions): boolean;
+/** Coarse runtime bucket — never anything machine-identifying. */
+export declare function detectRuntime(): 'browser' | 'webcontainer' | 'bun' | 'node' | 'unknown';
+/**
+ * Record an anonymous, aggregate event. No-op unless telemetry is enabled AND a
+ * collector URL is configured. Never blocks, never throws.
+ */
+export declare function track(event: string, props?: Record<string, unknown>, opts?: TelemetryOptions): void;

package/dist/telemetry.js

@@ -0,0 +1,153 @@
+// Anonymous, opt-out usage telemetry. The goal is a single, honest question:
+// "are people adopting the SDK, and which parts?" — answered in AGGREGATE, never
+// per-user. This module is deliberately conservative about what it can ever send.
+//
+// HARD GUARANTEES (enforced here, not just by convention):
+//   • It NEVER sends: repo/remote URLs, project/package names, file paths, source
+//     code, prompts, messages, tool arguments, LLM responses, API keys, or
+//     endpoints/base URLs. `track()` whitelists prop keys and keeps only booleans
+//     + a few coarse string buckets — anything else is dropped.
+//   • Off with one switch: `ANYCLAUDE_TELEMETRY=0`, `DO_NOT_TRACK=1`, any `CI`,
+//     a `disableTelemetry` option, browser `localStorage['anyclaude_telemetry']='0'`,
+//     or `globalThis.__ANYCLAUDE_NO_TELEMETRY__ = true`.
+//   • No endpoint configured ⇒ no-op (it can't send anywhere by default).
+//   • Fire-and-forget: never blocks, never throws, swallows all errors.
+//
+// See TELEMETRY.md for the full disclosure.
+import { uuid } from './util/ids.js';
+/** Bump on release so adoption can be bucketed by version. */
+export const TELEMETRY_SDK_VERSION = '0.7.0';
+// Set this (or `ANYCLAUDE_TELEMETRY_URL`) to your collector. Empty ⇒ no-op.
+const DEFAULT_TELEMETRY_URL = '';
+// Only these prop keys are ever transmitted, and only with safe value types.
+// Booleans pass through; these specific string keys pass through as-is (they are
+// coarse buckets we set ourselves — never free-form / user data).
+const ALLOWED_STRING_KEYS = new Set(['model_family', 'event_detail']);
+function readEnv(name) {
+    const p = globalThis.process;
+    return p?.env?.[name];
+}
+/** Resolve whether telemetry may run, honoring every documented opt-out. */
+export function telemetryEnabled(opts) {
+    if (opts?.disabled)
+        return false;
+    const flag = (readEnv('ANYCLAUDE_TELEMETRY') ?? '').toLowerCase();
+    if (flag === '0' || flag === 'false' || flag === 'off' || flag === 'no')
+        return false;
+    const dnt = (readEnv('DO_NOT_TRACK') ?? '').toLowerCase();
+    if (dnt === '1' || dnt === 'true')
+        return false;
+    if (readEnv('CI'))
+        return false;
+    try {
+        const g = globalThis;
+        if (g.__ANYCLAUDE_NO_TELEMETRY__ === true)
+            return false;
+        const v = g.localStorage?.getItem('anyclaude_telemetry');
+        if (v === '0' || v === 'off' || v === 'false')
+            return false;
+    }
+    catch {
+        /* localStorage may throw in sandboxed contexts */
+    }
+    return true;
+}
+function telemetryUrl(opts) {
+    return opts?.url || readEnv('ANYCLAUDE_TELEMETRY_URL') || DEFAULT_TELEMETRY_URL;
+}
+/** Coarse runtime bucket — never anything machine-identifying. */
+export function detectRuntime() {
+    const g = globalThis;
+    // WebContainer sets process.versions.webcontainer.
+    if (g.process?.versions?.webcontainer)
+        return 'webcontainer';
+    if (typeof g.window !== 'undefined' && typeof g.document !== 'undefined')
+        return 'browser';
+    if (g.Bun || g.process?.versions?.bun)
+        return 'bun';
+    if (g.process?.versions?.node)
+        return 'node';
+    return 'unknown';
+}
+// A random, NON-identifying id. Persisted in browser localStorage so repeated
+// runs on one origin coalesce; per-process otherwise. Not tied to machine/user/IP.
+let cachedInstallId = null;
+function installId() {
+    if (cachedInstallId)
+        return cachedInstallId;
+    try {
+        const ls = globalThis.localStorage;
+        if (ls) {
+            const existing = ls.getItem('anyclaude_install_id');
+            if (existing)
+                return (cachedInstallId = existing);
+            const fresh = uuid();
+            ls.setItem('anyclaude_install_id', fresh);
+            return (cachedInstallId = fresh);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return (cachedInstallId = uuid());
+}
+/** Keep only booleans + the allowlisted coarse string buckets. Everything else is dropped. */
+function safeProps(props) {
+    const out = {};
+    for (const [k, v] of Object.entries(props)) {
+        if (typeof v === 'boolean')
+            out[k] = v;
+        else if (typeof v === 'number' && Number.isFinite(v))
+            out[k] = v;
+        else if (typeof v === 'string' && ALLOWED_STRING_KEYS.has(k))
+            out[k] = v.slice(0, 40);
+    }
+    return out;
+}
+let noticeShown = false;
+function showNoticeOnce() {
+    if (noticeShown)
+        return;
+    noticeShown = true;
+    try {
+        const log = globalThis.console;
+        log?.error?.('[anyclaude-sdk] Anonymous usage telemetry is on (version + runtime + which features, no code/prompts/repo/keys). ' +
+            'Opt out: ANYCLAUDE_TELEMETRY=0 (or DO_NOT_TRACK=1). See TELEMETRY.md.');
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Record an anonymous, aggregate event. No-op unless telemetry is enabled AND a
+ * collector URL is configured. Never blocks, never throws.
+ */
+export function track(event, props = {}, opts) {
+    try {
+        if (!telemetryEnabled(opts))
+            return;
+        const url = telemetryUrl(opts);
+        if (!url)
+            return;
+        const f = globalThis.fetch;
+        if (!f)
+            return;
+        showNoticeOnce();
+        const body = JSON.stringify({
+            event,
+            sdk_version: TELEMETRY_SDK_VERSION,
+            runtime: detectRuntime(),
+            install: installId(),
+            ...safeProps(props),
+        });
+        void f(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body,
+            keepalive: true,
+        }).catch(() => { });
+    }
+    catch {
+        /* telemetry must never affect the host app */
+    }
+}

package/dist/types/index.d.ts

@@ -162,7 +162,17 @@ export type SDKCompactBoundaryMessage = {
     subtype: 'compact_boundary';
     compact_metadata: {
         trigger: 'manual' | 'auto';
+        /** Transcript token estimate when compaction began. */
         pre_tokens: number;
+        /**
+         * Compaction phase: `'start'` is emitted BEFORE the (possibly slow)
+         * summarization so a UI can show a live "compacting…" indicator; `'end'`
+         * is emitted after, with `post_tokens` set. Absent ⇒ treat as `'end'`
+         * (back-compat: pre-0.6.2 only emitted the post-compaction boundary).
+         */
+        status?: 'start' | 'end';
+        /** Transcript token estimate after compaction (only on `status: 'end'`). */
+        post_tokens?: number;
     };
     uuid: string;
     session_id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anyclaude-sdk",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Standalone, browser-compatible SDK providing Claude Code agent capabilities (tools, tool loop, multi-turn, MCP, sub-agents, sessions) against any OpenAI/Anthropic-compatible LLM endpoint. Runs in the browser (WebContainer), Node, and Bun — no backend required.",
   "type": "module",
   "main": "./dist/index.js",
@@ -71,6 +71,10 @@
     "./anthropic-endpoint": {
       "types": "./dist/anthropic-endpoint.d.ts",
       "import": "./dist/anthropic-endpoint.js"
+    },
+    "./telemetry": {
+      "types": "./dist/telemetry.d.ts",
+      "import": "./dist/telemetry.js"
     }
   },
   "sideEffects": false,