@tiny-fish/cli 0.12.1-next.135 → 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.d.ts

@@ -1,8 +1,9 @@
 import { Command } from "commander";
+export declare const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 export declare const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI and skill.";
 export declare const DEFAULT_ONBOARDING_PROMPT: string;
 export declare const OPENCLAW_ONBOARDING_PROMPT: string;
-export type AgentClient = "claude-code" | "codex" | "hermes" | "openclaw";
+export type AgentClient = "claude-code" | "codex" | "cursor" | "hermes" | "openclaw";
 /** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
 export declare class ConnectInterruptedError extends Error {
 }
@@ -36,5 +37,10 @@ export declare function connectOpenClaw(options: {
     launch: boolean;
     installCli?: boolean;
 }): Promise<void>;
+/** Writes mcp.json directly — no `cursor mcp add` exists. */
+export declare function connectCursor(options: {
+    apiKey?: string;
+    mcpUrl: string;
+}): Promise<void>;
 export declare function launchAgent(client: AgentClient): void;
 export declare function registerConnect(program: Command): void;

package/dist/commands/connect.js

@@ -1,10 +1,13 @@
-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";
-const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
+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;
 const HERMES_SEED_TIMEOUT_MS = 120_000;
@@ -219,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;
@@ -252,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++) {
@@ -597,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.`);
@@ -675,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.");
@@ -687,6 +668,40 @@ export async function connectOpenClaw(options) {
         settle(state, telemetry, "completed");
     });
 }
+/** Writes mcp.json directly — no `cursor mcp add` exists. */
+export async function connectCursor(options) {
+    const telemetry = createConnectTelemetry(options.mcpUrl, "cursor", options.apiKey);
+    const state = { stage: "prerequisite_check", settled: false };
+    await runGuarded(state, telemetry, () => {
+        telemetry.track("started");
+        telemetry.track("checkpoint", { phase: "prerequisite_ok" });
+        state.stage = "registration";
+        errLine("Adding TinyFish to Cursor...");
+        const mcpUrl = new URL(options.mcpUrl);
+        mcpUrl.searchParams.set("source", CONNECT_SOURCE);
+        mcpUrl.searchParams.set("client", "cursor");
+        // Attempt id rides telemetry only; persisting it would break idempotency.
+        const result = writeCursorMcpConfig(mcpUrl.toString());
+        if (result.status === "corrupt_skip") {
+            throw new Error(`Could not update ${cursorMcpPath()}: existing file could not be read or is not valid JSON (${result.error}). ` +
+                `Fix the file, then re-run: tinyfish connect cursor`);
+        }
+        if (result.backupPath) {
+            errLine(`Backed up existing Cursor MCP config to ${result.backupPath}`);
+        }
+        telemetry.track("checkpoint", { phase: "registered" });
+        state.stage = "authentication";
+        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");
+        errLine('Settings -> Tools & MCP and click Connect on "tinyfish" to sign in.');
+        settle(state, telemetry, "completed");
+    });
+}
 export function launchAgent(client) {
     if (client === "claude-code") {
         launchNativeMcpClient(CLAUDE_CODE);
@@ -697,15 +712,23 @@ export function launchAgent(client) {
     else if (client === "hermes") {
         launchNativeMcpClient(HERMES);
     }
-    else {
+    else if (client === "openclaw") {
         launchOpenClawWalkthrough();
     }
+    else if (client === "cursor") {
+        // Cursor has no chat CLI to launch.
+        throw new Error("Cursor has no launchable walkthrough. Open Cursor and start chatting.");
+    }
+    else {
+        const unhandled = client;
+        throw new Error(`No launch support for client: ${String(unhandled)}`);
+    }
 }
 export function registerConnect(program) {
     program
         .command("connect")
         .description("Connect TinyFish to an AI agent")
-        .argument("<client>", "Agent client to connect (claude-code, codex, hermes, or openclaw)")
+        .argument("<client>", "Agent client to connect (claude-code, codex, cursor, hermes, or openclaw)")
         .option("--api-key <apiKey>", "TinyFish API key to persist for the installed skill")
         .option("--launch", "Launch the agent and start the TinyFish walkthrough")
         .option("--url <mcpUrl>", "MCP endpoint override")
@@ -740,8 +763,18 @@ export function registerConnect(program) {
         else if (client === "openclaw") {
             await connectOpenClaw({ mcpUrl: connectOptions.mcpUrl, launch: connectOptions.launch });
         }
+        else if (client === "cursor") {
+            // `connect <client> --launch` is the shape every doc uses; connect anyway, then say
+            // why nothing launched rather than throwing away a working install.
+            await connectCursor({ apiKey: connectOptions.apiKey, mcpUrl: connectOptions.mcpUrl });
+            if (connectOptions.launch) {
+                errLine("Cursor has no launchable walkthrough. Open Cursor and start chatting.");
+            }
+        }
         else {
-            throw new Error(`Unsupported client: ${client}. Supported clients: claude-code, codex, hermes, openclaw`);
+            throw new Error("Unsupported client: " +
+                client +
+                ". Supported clients: claude-code, codex, cursor, hermes, openclaw");
         }
     });
 }

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/cursor-config.d.ts

@@ -0,0 +1,13 @@
+export declare function cursorConfigDir(): string;
+export declare function cursorMcpPath(): string;
+export interface CursorMcpWriteResult {
+    status: "written" | "unchanged" | "corrupt_skip";
+    backupPath?: string;
+    error?: string;
+}
+/** Dry-run description of the pending write; touches nothing. */
+export declare function planCursorWrite(mcpUrl: string): string;
+/** Merges only the `tinyfish` key; skips unreadable/corrupt files rather than clobber. */
+export declare function writeCursorMcpConfig(mcpUrl: string): CursorMcpWriteResult;
+/** Removes only the `tinyfish` key. */
+export declare function removeCursorMcpServer(): CursorMcpWriteResult;

package/dist/lib/cursor-config.js

@@ -0,0 +1,115 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+// The one config file the CLI writes directly — hence backup/merge rigor.
+const TINYFISH_SERVER_KEY = "tinyfish";
+export function cursorConfigDir() {
+    return path.join(os.homedir(), ".cursor");
+}
+export function cursorMcpPath() {
+    return path.join(cursorConfigDir(), "mcp.json");
+}
+function isPlainRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function buildTinyfishServerEntry(mcpUrl) {
+    return { url: mcpUrl };
+}
+function parseMcpJson(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isPlainRecord(parsed))
+            return { ok: false, error: "mcp.json root is not a JSON object" };
+        if ("mcpServers" in parsed && !isPlainRecord(parsed.mcpServers)) {
+            return { ok: false, error: "mcp.json mcpServers is not a JSON object" };
+        }
+        return { ok: true, value: parsed };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+// Non-ENOENT read failures count as corruption: skip, never clobber.
+function readExisting() {
+    let raw;
+    try {
+        raw = fs.readFileSync(cursorMcpPath(), "utf8");
+    }
+    catch (e) {
+        if (e?.code === "ENOENT")
+            return { parsed: {} };
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    const parsed = parseMcpJson(raw);
+    if (!parsed.ok)
+        return { error: parsed.error };
+    return { raw, parsed: parsed.value };
+}
+/** Dry-run description of the pending write; touches nothing. */
+export function planCursorWrite(mcpUrl) {
+    const existing = readExisting();
+    const filePath = cursorMcpPath();
+    if ("error" in existing) {
+        return `${filePath}: existing file is corrupt (${existing.error}) — would skip and leave it untouched`;
+    }
+    const servers = existing.parsed.mcpServers;
+    const current = isPlainRecord(servers) ? servers[TINYFISH_SERVER_KEY] : undefined;
+    if (JSON.stringify(current) === JSON.stringify(buildTinyfishServerEntry(mcpUrl))) {
+        return `${filePath}: already has the tinyfish MCP entry — no change`;
+    }
+    return existing.raw === undefined
+        ? `${filePath}: would create with a "tinyfish" MCP server entry`
+        : `${filePath}: would back up to a timestamped copy, then merge in the "tinyfish" MCP server entry`;
+}
+// Backup, then atomic temp+rename; pid avoids same-millisecond backup collisions.
+function commitServers(filePath, existing, servers) {
+    fs.mkdirSync(cursorConfigDir(), { recursive: true, mode: 0o700 });
+    let backupPath;
+    if (existing.raw !== undefined) {
+        backupPath = `${filePath}.bak-${Date.now()}-${process.pid}`;
+        fs.writeFileSync(backupPath, existing.raw, { mode: 0o600 });
+    }
+    const next = { ...existing.parsed, mcpServers: servers };
+    const tmpPath = `${filePath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmpPath, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    try {
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (e) {
+        fs.rmSync(tmpPath, { force: true });
+        throw e;
+    }
+    return { status: "written", backupPath };
+}
+/** Merges only the `tinyfish` key; skips unreadable/corrupt files rather than clobber. */
+export function writeCursorMcpConfig(mcpUrl) {
+    const filePath = cursorMcpPath();
+    const existing = readExisting();
+    if ("error" in existing)
+        return { status: "corrupt_skip", error: existing.error };
+    const servers = isPlainRecord(existing.parsed.mcpServers)
+        ? { ...existing.parsed.mcpServers }
+        : {};
+    const nextEntry = buildTinyfishServerEntry(mcpUrl);
+    if (JSON.stringify(servers[TINYFISH_SERVER_KEY]) === JSON.stringify(nextEntry)) {
+        return { status: "unchanged" };
+    }
+    servers[TINYFISH_SERVER_KEY] = nextEntry;
+    return commitServers(filePath, existing, servers);
+}
+/** Removes only the `tinyfish` key. */
+export function removeCursorMcpServer() {
+    const filePath = cursorMcpPath();
+    const existing = readExisting();
+    if ("error" in existing)
+        return { status: "corrupt_skip", error: existing.error };
+    if (existing.raw === undefined)
+        return { status: "unchanged" };
+    const servers = isPlainRecord(existing.parsed.mcpServers)
+        ? { ...existing.parsed.mcpServers }
+        : {};
+    if (!(TINYFISH_SERVER_KEY in servers))
+        return { status: "unchanged" };
+    delete servers[TINYFISH_SERVER_KEY];
+    return commitServers(filePath, existing, servers);
+}

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.135",
+  "version": "0.12.1-next.138",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {