@tiny-fish/cli 0.12.1-next.137 → 0.12.1-next.138

package/README.md

@@ -277,6 +277,14 @@ TINYFISH_DEBUG=1 tinyfish agent run "..." --url https://example.com
 tinyfish --debug agent run "..." --url https://example.com
 ```
 
+### Telemetry
+
+The CLI reports setup outcomes (which harnesses connected, whether verification passed) and
+checks npm once a day for a newer CLI. Set `TINYFISH_NO_TELEMETRY` to any value other than
+`0`/`false` to disable both. API keys are never sent — only a SHA-256 lookup hash, and only to
+TinyFish-owned origins (`*.tinyfish.ai`, `*.tinyfish.io`) or a local development endpoint
+(`localhost`, `127.0.0.1`, `[::1]`).
+
 ## CI/CD
 
 ```yaml

package/dist/commands/connect.js

@@ -1,10 +1,12 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import spawn from "cross-spawn";
 import { CONNECT_SOURCE, loadConfig, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, writeConfig, } from "../lib/auth.js";
 import { CLI_VERSION } from "../lib/constants.js";
 import { cursorMcpPath, writeCursorMcpConfig } from "../lib/cursor-config.js";
 import { errLine } from "../lib/output.js";
+import { telemetryDisabled, telemetryHeaders } from "../lib/setup-telemetry.js";
+import { recordInstalledVersion } from "../lib/version-marker.js";
 export const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
 const SKILL_INSTALL_TIMEOUT_MS = 120_000;
@@ -220,27 +222,6 @@ const OPENCLAW = {
         unavailableMessage: OPENCLAW_SKILL_UNAVAILABLE_MESSAGE,
     },
 };
-// TinyFish-owned domains plus loopback are the only origins the API key may be sent to.
-// `--url` accepts any http(s) URL, so a user-supplied origin must never receive the key.
-const TRUSTED_TELEMETRY_HOST_SUFFIXES = [".tinyfish.ai", ".tinyfish.io"];
-const TRUSTED_TELEMETRY_LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
-function isTrustedTelemetryOrigin(endpoint) {
-    let url;
-    try {
-        url = new URL(endpoint);
-    }
-    catch {
-        return false;
-    }
-    const host = url.hostname.toLowerCase();
-    // Loopback may use http for local dev; every other trusted origin must be https so the
-    // key is never sent over cleartext.
-    if (TRUSTED_TELEMETRY_LOOPBACK_HOSTS.includes(host))
-        return true;
-    if (url.protocol !== "https:")
-        return false;
-    return TRUSTED_TELEMETRY_HOST_SUFFIXES.some((suffix) => host === suffix.slice(1) || host.endsWith(suffix));
-}
 function storedApiKey() {
     try {
         return loadConfig().api_key;
@@ -253,14 +234,11 @@ function createConnectTelemetry(mcpUrl, client, apiKey) {
     const attemptId = randomUUID();
     const endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
     const telemetryKey = apiKey || process.env["TINYFISH_API_KEY"] || storedApiKey();
-    const headers = { "content-type": "application/json" };
-    // SHA-256 lookup key only — the raw key never rides a telemetry request
-    // (OWASP: keep credentials out of anything logging infra might capture).
-    if (telemetryKey && validateKeyFormat(telemetryKey) && isTrustedTelemetryOrigin(endpoint)) {
-        headers["x-api-key-lookup"] = createHash("sha256").update(telemetryKey).digest("hex");
-    }
+    const headers = telemetryHeaders(endpoint, telemetryKey);
     const pending = [];
     async function deliver(body) {
+        if (telemetryDisabled())
+            return;
         // One retry: stale keep-alive sockets eat post-install POSTs. 5xx retries;
         // 4xx never will (schema mismatch, e.g. new stages hitting an old server).
         for (let attempt = 0; attempt < 2; attempt++) {
@@ -598,6 +576,7 @@ async function connectNativeMcpClient(client, options) {
         // Persist once here (skill installed + authenticated) so both success paths, launch
         // or not, record the install; buildConnectHeaders reads it on subsequent requests.
         saveConnectContext(client.connectClient, telemetry.attemptId);
+        recordInstalledVersion();
         errLine(UPGRADE_HINT);
         if (!options.launch) {
             errLine(`TinyFish is connected. Open ${client.displayName} to start using it.`);
@@ -676,6 +655,7 @@ export async function connectOpenClaw(options) {
         }
         telemetry.track("checkpoint", { phase: "authenticated" });
         saveConnectContext("openclaw", telemetry.attemptId);
+        recordInstalledVersion();
         errLine(UPGRADE_HINT);
         if (!options.launch) {
             errLine("TinyFish is connected. Open OpenClaw to start using it.");
@@ -714,6 +694,7 @@ export async function connectCursor(options) {
         ensureCliAuthenticated("cursor", options.apiKey);
         telemetry.track("checkpoint", { phase: "authenticated" });
         saveConnectContext("cursor", telemetry.attemptId);
+        recordInstalledVersion();
         // A server written into mcp.json lands unauthenticated: only Cursor's own "Add to
         // Cursor" deep link auto-starts OAuth, so name the click or the install never completes.
         errLine("Added to Cursor. Restart Cursor (or reload the window), then open");

package/dist/lib/client.d.ts

@@ -7,7 +7,7 @@ export declare function buildConnectHeaders(connect: ConnectMap, caller: string
 export declare function runSync(req: CliAgentRunParams, apiKey: string): Promise<AgentRunResponse>;
 export declare function runAsync(req: CliAgentRunParams, apiKey: string): Promise<AgentRunAsyncResponse>;
 export declare function runStream(req: CliAgentRunParams, apiKey: string, signal?: AbortSignal): AsyncGenerator<AgentRunWithStreamingResponse>;
-export declare function listRuns(opts: RunListParams, apiKey: string): Promise<RunListResponse>;
+export declare function listRuns(opts: RunListParams, apiKey: string, timeout?: number): Promise<RunListResponse>;
 export declare function getRun(runId: string, apiKey: string): Promise<Run>;
 export declare function getRunSteps(runId: string, apiKey: string): Promise<RunStepsResponse>;
 export declare function searchQuery(params: SearchQueryParams, apiKey: string): Promise<SearchQueryResponse>;

package/dist/lib/client.js

@@ -256,9 +256,9 @@ export async function* runStream(req, apiKey, signal) {
         }
     }
 }
-export async function listRuns(opts, apiKey) {
+export async function listRuns(opts, apiKey, timeout) {
     try {
-        return await createSdkClient(apiKey).runs.list(opts);
+        return await createSdkClient(apiKey, timeout).runs.list(opts);
     }
     catch (error) {
         rethrowSdkError(error);

package/dist/lib/harness-detect.d.ts

@@ -0,0 +1,9 @@
+export declare const FIVE_HARNESSES: readonly ["claude-code", "codex", "cursor", "hermes", "openclaw"];
+export type FiveHarness = (typeof FIVE_HARNESSES)[number];
+export declare function harnessConfigPath(harness: FiveHarness): string;
+export interface HarnessDetection {
+    harness: FiveHarness;
+    detected: boolean;
+    configPath: string;
+}
+export declare function detectInstalledHarnesses(): HarnessDetection[];

package/dist/lib/harness-detect.js

@@ -0,0 +1,28 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+export const FIVE_HARNESSES = ["claude-code", "codex", "cursor", "hermes", "openclaw"];
+// Presence detection only — dir existence means "installed", nothing more.
+const CONFIG_DIRS = {
+    "claude-code": ".claude",
+    codex: ".codex",
+    cursor: ".cursor",
+    hermes: ".hermes",
+    openclaw: ".openclaw",
+};
+export function harnessConfigPath(harness) {
+    return path.join(os.homedir(), CONFIG_DIRS[harness]); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
+}
+export function detectInstalledHarnesses() {
+    return FIVE_HARNESSES.map((harness) => {
+        const configPath = harnessConfigPath(harness);
+        let detected;
+        try {
+            detected = fs.statSync(configPath).isDirectory();
+        }
+        catch {
+            detected = false;
+        }
+        return { harness, detected, configPath };
+    });
+}

package/dist/lib/setup-telemetry.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+/**
+ * `TINYFISH_NO_TELEMETRY` suppresses ALL CLI-emitted network analytics
+ * (setup_completed, connect-event, update check). Any value except `0`/`false`
+ * opts out — a privacy switch must not fail closed on `true`.
+ */
+export declare function telemetryDisabled(): boolean;
+export declare function isTrustedTelemetryOrigin(endpoint: string): boolean;
+/** SHA-256 lookup key only, and only to trusted origins — the raw key never rides telemetry. */
+export declare function telemetryHeaders(endpoint: string, apiKey?: string): Record<string, string>;
+declare const harnessResultSchema: z.ZodObject<{
+    harness: z.ZodEnum<{
+        openclaw: "openclaw";
+        cursor: "cursor";
+        codex: "codex";
+        hermes: "hermes";
+        "claude-code": "claude-code";
+    }>;
+    detected: z.ZodBoolean;
+    installed: z.ZodBoolean;
+    verify_depth: z.ZodNullable<z.ZodEnum<{
+        health: "health";
+        "health+auth": "health+auth";
+    }>>;
+    verify_ok: z.ZodNullable<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const setupCompletedPayloadSchema: z.ZodObject<{
+    harnesses: z.ZodArray<z.ZodObject<{
+        harness: z.ZodEnum<{
+            openclaw: "openclaw";
+            cursor: "cursor";
+            codex: "codex";
+            hermes: "hermes";
+            "claude-code": "claude-code";
+        }>;
+        detected: z.ZodBoolean;
+        installed: z.ZodBoolean;
+        verify_depth: z.ZodNullable<z.ZodEnum<{
+            health: "health";
+            "health+auth": "health+auth";
+        }>>;
+        verify_ok: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    cli_version: z.ZodString;
+}, z.core.$strip>;
+export type SetupCompletedPayload = z.infer<typeof setupCompletedPayloadSchema>;
+export type HarnessResult = z.infer<typeof harnessResultSchema>;
+/** Fire-and-forget, 2s cap; raw keys never ride telemetry. */
+export declare function sendSetupCompleted(mcpUrl: string, harnesses: HarnessResult[], apiKey?: string): Promise<void>;
+export {};

package/dist/lib/setup-telemetry.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { validateKeyFormat } from "./auth.js";
+import { CLI_VERSION } from "./constants.js";
+import { FIVE_HARNESSES } from "./harness-detect.js";
+import { errLine } from "./output.js";
+const SETUP_TELEMETRY_TIMEOUT_MS = 2_000;
+/**
+ * `TINYFISH_NO_TELEMETRY` suppresses ALL CLI-emitted network analytics
+ * (setup_completed, connect-event, update check). Any value except `0`/`false`
+ * opts out — a privacy switch must not fail closed on `true`.
+ */
+export function telemetryDisabled() {
+    const value = (process.env["TINYFISH_NO_TELEMETRY"] ?? "").trim().toLowerCase();
+    return value !== "" && value !== "0" && value !== "false";
+}
+// TinyFish-owned domains plus loopback are the only origins the API key may be sent to.
+// `--url` accepts any http(s) URL, so a user-supplied origin must never receive the key.
+const TRUSTED_TELEMETRY_HOST_SUFFIXES = [".tinyfish.ai", ".tinyfish.io"];
+const TRUSTED_TELEMETRY_LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+export function isTrustedTelemetryOrigin(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        return false;
+    }
+    const host = url.hostname.toLowerCase();
+    // Loopback may use http for local dev; every other trusted origin must be https so the
+    // key is never sent over cleartext.
+    if (TRUSTED_TELEMETRY_LOOPBACK_HOSTS.includes(host))
+        return true;
+    if (url.protocol !== "https:")
+        return false;
+    return TRUSTED_TELEMETRY_HOST_SUFFIXES.some((suffix) => host === suffix.slice(1) || host.endsWith(suffix));
+}
+/** SHA-256 lookup key only, and only to trusted origins — the raw key never rides telemetry. */
+export function telemetryHeaders(endpoint, apiKey) {
+    const headers = { "content-type": "application/json" };
+    if (apiKey && validateKeyFormat(apiKey) && isTrustedTelemetryOrigin(endpoint)) {
+        headers["x-api-key-lookup"] = createHash("sha256").update(apiKey).digest("hex");
+    }
+    return headers;
+}
+const harnessResultSchema = z.object({
+    harness: z.enum(FIVE_HARNESSES),
+    detected: z.boolean(),
+    installed: z.boolean(),
+    verify_depth: z.enum(["health", "health+auth"]).nullable(),
+    verify_ok: z.boolean().nullable(),
+});
+export const setupCompletedPayloadSchema = z.object({
+    harnesses: z
+        .array(harnessResultSchema)
+        .length(FIVE_HARNESSES.length)
+        .refine((results) => new Set(results.map((r) => r.harness)).size === FIVE_HARNESSES.length, {
+        message: "expected one result per harness",
+    }),
+    cli_version: z.string(),
+});
+/** Fire-and-forget, 2s cap; raw keys never ride telemetry. */
+export async function sendSetupCompleted(mcpUrl, harnesses, apiKey) {
+    if (telemetryDisabled())
+        return;
+    let endpoint;
+    let body;
+    try {
+        // Parse inside try — schema violation must not crash finished setup.
+        const payload = setupCompletedPayloadSchema.parse({ harnesses, cli_version: CLI_VERSION });
+        endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
+        body = JSON.stringify({ event: "setup_completed", ...payload });
+    }
+    catch (e) {
+        if (process.env["TINYFISH_DEBUG"]) {
+            errLine(`setup telemetry skipped: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return;
+    }
+    const headers = telemetryHeaders(endpoint, apiKey);
+    // One retry: stale keep-alive sockets eat post-install POSTs, and this is the
+    // headline `--all` metric. 5xx retries; 4xx never will.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers,
+                body,
+                redirect: "error",
+                signal: AbortSignal.timeout(SETUP_TELEMETRY_TIMEOUT_MS),
+            });
+            if (response.ok)
+                return;
+            if (response.status < 500) {
+                if (process.env["TINYFISH_DEBUG"]) {
+                    errLine(`setup telemetry rejected: HTTP ${response.status}`);
+                }
+                return;
+            }
+        }
+        catch (e) {
+            if (process.env["TINYFISH_DEBUG"]) {
+                errLine(`setup telemetry failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+    }
+}

package/dist/lib/verify.d.ts

@@ -0,0 +1,10 @@
+export type VerifyDepth = "health" | "health+auth";
+export interface VerifyResult {
+    depth: VerifyDepth;
+    ok: boolean;
+    reason?: string;
+}
+/** Reachability check. Verify failure is a warning, never install failure. */
+export declare function verifyMcpHealth(mcpUrl: string): Promise<VerifyResult>;
+/** Authenticated check — only where the CLI holds the key (Cursor, OpenClaw). */
+export declare function verifyMcpAuth(apiKey: string): Promise<VerifyResult>;

package/dist/lib/verify.js

@@ -0,0 +1,36 @@
+import { listRuns } from "./client.js";
+const VERIFY_TIMEOUT_MS = 5_000;
+/** Reachability check. Verify failure is a warning, never install failure. */
+export async function verifyMcpHealth(mcpUrl) {
+    try {
+        const response = await fetch(mcpUrl, {
+            method: "GET",
+            // Redirect (captive portal, typo'd --url) is not healthy.
+            redirect: "error",
+            signal: AbortSignal.timeout(VERIFY_TIMEOUT_MS),
+        });
+        // MCP rejects bare GET with 4xx — still proves endpoint routed.
+        if (response.status >= 500) {
+            return { depth: "health", ok: false, reason: `endpoint returned HTTP ${response.status}` };
+        }
+        return { depth: "health", ok: true };
+    }
+    catch (e) {
+        return {
+            depth: "health",
+            ok: false,
+            reason: e instanceof Error ? e.message : "network error reaching MCP endpoint",
+        };
+    }
+}
+/** Authenticated check — only where the CLI holds the key (Cursor, OpenClaw). */
+export async function verifyMcpAuth(apiKey) {
+    try {
+        // Bound it: the SDK default is 600s, and a warning-only check must never hang an install.
+        await listRuns({ limit: 1 }, apiKey, VERIFY_TIMEOUT_MS);
+        return { depth: "health+auth", ok: true };
+    }
+    catch (e) {
+        return { depth: "health+auth", ok: false, reason: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/lib/version-marker.d.ts

@@ -0,0 +1,10 @@
+/** Install-time, offline-safe; best-effort — never fails a finished install. */
+export declare function recordInstalledVersion(): void;
+interface UpdateCheckResult {
+    updateAvailable: boolean;
+    latest?: string;
+}
+/** Throttled npm-currency check; never auto-mutates the install. */
+export declare function checkForCliUpdate(now?: number): Promise<UpdateCheckResult>;
+export declare function printUpdateNoticeIfDrifted(): Promise<void>;
+export {};

package/dist/lib/version-marker.js

@@ -0,0 +1,109 @@
+import * as fs from "fs";
+import * as path from "path";
+import { z } from "zod";
+import { configDir } from "./auth.js";
+import { CLI_VERSION } from "./constants.js";
+import { errLine } from "./output.js";
+import { telemetryDisabled } from "./setup-telemetry.js";
+const MARKER_FILE = "skill-version-marker.json";
+const THROTTLE_MS = 24 * 60 * 60 * 1000;
+const CHECK_TIMEOUT_MS = 5_000;
+// npm is the only currency signal with a publisher behind it: the cookbook repo has no
+// releases and no release automation, so a tag check would report "up to date" forever.
+const REGISTRY_URL = "https://registry.npmjs.org/@tiny-fish/cli/latest";
+const markerSchema = z.object({
+    last_checked_at: z.number().optional(),
+    last_known_latest: z.string().optional(),
+});
+function markerPath() {
+    return path.join(configDir(), MARKER_FILE);
+}
+function readMarker() {
+    try {
+        const parsed = markerSchema.safeParse(JSON.parse(fs.readFileSync(markerPath(), "utf8")));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeMarker(state) {
+    fs.mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    const tmpPath = `${markerPath()}.tmp-${process.pid}`;
+    fs.writeFileSync(tmpPath, JSON.stringify(state), { mode: 0o600 });
+    fs.renameSync(tmpPath, markerPath());
+}
+/** Install-time, offline-safe; best-effort — never fails a finished install. */
+export function recordInstalledVersion() {
+    try {
+        writeMarker({ ...readMarker() });
+    }
+    catch {
+        // marker is a nice-to-have
+    }
+}
+const SEMVER = /^v?(\d+)\.(\d+)\.(\d+)$/;
+/** Strictly newer; false on unparsable input. */
+function isNewer(current, latest) {
+    const c = SEMVER.exec(current);
+    const l = SEMVER.exec(latest);
+    if (!c || !l)
+        return false;
+    for (let i = 1; i <= 3; i++) {
+        const cn = Number(c[i]);
+        const ln = Number(l[i]);
+        if (ln !== cn)
+            return ln > cn;
+    }
+    return false;
+}
+/** Throttled npm-currency check; never auto-mutates the install. */
+export async function checkForCliUpdate(now = Date.now()) {
+    const marker = readMarker();
+    // No marker means the CLI never installed anything — nothing to nag about.
+    if (!marker || telemetryDisabled())
+        return { updateAvailable: false };
+    const cached = () => ({
+        updateAvailable: marker.last_known_latest !== undefined && isNewer(CLI_VERSION, marker.last_known_latest),
+        ...(marker.last_known_latest !== undefined ? { latest: marker.last_known_latest } : {}),
+    });
+    // Time-based only — failed fetch must not stall every invocation.
+    if (marker.last_checked_at !== undefined && now - marker.last_checked_at < THROTTLE_MS) {
+        return cached();
+    }
+    let latest;
+    try {
+        const response = await fetch(REGISTRY_URL, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
+        });
+        if (response.ok) {
+            const body = (await response.json());
+            if (typeof body.version === "string")
+                latest = body.version;
+        }
+    }
+    catch {
+        // Unreachable registry — don't fail setup, don't erase the cache.
+    }
+    try {
+        writeMarker({
+            ...marker,
+            last_checked_at: now,
+            last_known_latest: latest ?? marker.last_known_latest,
+        });
+    }
+    catch {
+        // best-effort
+    }
+    // Fall back to the cache so consecutive invocations can't disagree.
+    if (!latest)
+        return cached();
+    return { updateAvailable: isNewer(CLI_VERSION, latest), latest };
+}
+export async function printUpdateNoticeIfDrifted() {
+    const { updateAvailable } = await checkForCliUpdate();
+    if (updateAvailable) {
+        errLine("a newer TinyFish CLI is available — re-run `npx @tiny-fish/cli connect --all`");
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.12.1-next.137",
+  "version": "0.12.1-next.138",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {