@tiny-fish/cli 0.14.1-next.151 → 0.14.1-next.154

package/dist/commands/connect.d.ts

@@ -7,6 +7,12 @@ export type AgentClient = "claude-code" | "codex" | "cursor" | "hermes" | "openc
 /** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
 export declare class ConnectInterruptedError extends Error {
 }
+interface NativeConnectOptions {
+    apiKey?: string;
+    mcpUrl: string;
+    launch: boolean;
+    attemptId?: string;
+}
 export declare function installTinyFishCli(): void;
 /**
  * Refresh the skill we installed, for the harnesses we installed it in.
@@ -17,35 +23,22 @@ export declare function installTinyFishCli(): void;
  * every agent on the machine).
  */
 export declare function updateWebSkill(): void;
-export declare function connectClaudeCode(options: {
-    apiKey?: string;
-    mcpUrl: string;
-    launch: boolean;
-}): Promise<void>;
-export declare function connectCodex(options: {
-    apiKey?: string;
-    mcpUrl: string;
-    launch: boolean;
-}): Promise<void>;
-export declare function connectHermes(options: {
-    apiKey?: string;
-    mcpUrl: string;
-    launch: boolean;
-}): Promise<void>;
-export declare function connectOpencode(options: {
-    apiKey?: string;
-    mcpUrl: string;
-    launch: boolean;
-}): Promise<void>;
+export declare function connectClaudeCode(options: NativeConnectOptions): Promise<void>;
+export declare function connectCodex(options: NativeConnectOptions): Promise<void>;
+export declare function connectHermes(options: NativeConnectOptions): Promise<void>;
+export declare function connectOpencode(options: NativeConnectOptions): Promise<void>;
 export declare function connectOpenClaw(options: {
     mcpUrl: string;
     launch: boolean;
     installCli?: boolean;
+    attemptId?: string;
 }): Promise<void>;
 /** Writes mcp.json directly — no `cursor mcp add` exists. */
 export declare function connectCursor(options: {
     apiKey?: string;
     mcpUrl: string;
+    attemptId?: string;
 }): Promise<void>;
 export declare function launchAgent(client: AgentClient): void;
 export declare function registerConnect(program: Command): void;
+export {};

package/dist/commands/connect.js

@@ -7,7 +7,8 @@ import { cursorInstallDeeplink, cursorMcpPath, writeCursorMcpConfig, } from "../
 import { runConnectAll } from "../lib/connect-all.js";
 import { detectHumanInitiated } from "../lib/harness.js";
 import { emitNotice } from "../lib/notice.js";
-import { errLine } from "../lib/output.js";
+import { errLine, sanitizeLine } from "../lib/output.js";
+import { z } from "zod";
 import { installSignalGuard } from "../lib/signals.js";
 import { postConnectEvent, telemetryDisabled } from "../lib/setup-telemetry.js";
 import { verifyMcpAuth } from "../lib/verify.js";
@@ -58,6 +59,15 @@ export const OPENCLAW_ONBOARDING_PROMPT = "I just installed the TinyFish skill.
 /** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
 export class ConnectInterruptedError extends Error {
 }
+class PrerequisiteError extends Error {
+    failureReason;
+    harnessVersion;
+    constructor(message, failureReason, opts) {
+        super(message, { cause: opts?.cause });
+        this.failureReason = failureReason;
+        this.harnessVersion = opts?.harnessVersion;
+    }
+}
 function throwIfInterrupted(result) {
     // spawn.sync kills a timed-out child with SIGTERM, so signal alone would misread a slow
     // network as the user walking away. A timeout is a failure and must report as one.
@@ -78,14 +88,15 @@ function settle(state, telemetry, stage, detail) {
 // (npm/npx/OAuth waits) land here.
 function installConnectSignalGuard(state, telemetry) {
     return installSignalGuard(async () => {
-        if (state.settled)
-            return;
-        settle(state, telemetry, "aborted", { failedStage: state.stage });
-        errLine("Setup interrupted — run the command again to finish.");
+        if (!state.settled) {
+            settle(state, telemetry, "aborted", { failedStage: state.stage });
+            errLine("Setup interrupted — run the command again to finish.");
+        }
+        // Settled spans the whole post-install phase; the `completed` POST may still be in flight.
         await telemetry.flush();
     });
 }
-/** Shared terminal handling: interrupted → aborted (or completed post-install), else failed. */
+/** Shared terminal handling: interrupted → aborted, else failed. */
 async function runGuarded(state, telemetry, body) {
     const uninstallSignalGuard = installConnectSignalGuard(state, telemetry);
     try {
@@ -93,16 +104,17 @@ async function runGuarded(state, telemetry, body) {
     }
     catch (error) {
         if (error instanceof ConnectInterruptedError) {
-            if (state.stage === "walkthrough_launch") {
-                settle(state, telemetry, "completed");
-                return;
-            }
             settle(state, telemetry, "aborted", { failedStage: state.stage });
             errLine("Setup interrupted — run the command again to finish.");
             process.exitCode = 130;
             return;
         }
-        settle(state, telemetry, "failed", { failedStage: state.stage });
+        settle(state, telemetry, "failed", {
+            failedStage: state.stage,
+            ...(error instanceof PrerequisiteError
+                ? { failureReason: error.failureReason, harnessVersion: error.harnessVersion }
+                : {}),
+        });
         throw error;
     }
     finally {
@@ -252,8 +264,9 @@ const OPENCLAW = {
         unavailableMessage: OPENCLAW_SKILL_UNAVAILABLE_MESSAGE,
     },
 };
-function createConnectTelemetry(mcpUrl, client, apiKey) {
-    const attemptId = randomUUID();
+function createConnectTelemetry(mcpUrl, client, opts) {
+    // A setup-page id (via --url) joins "copied the command" to this install attempt.
+    const attemptId = opts?.attemptId ?? randomUUID();
     const endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
     const pending = [];
     async function deliver(body) {
@@ -265,7 +278,7 @@ function createConnectTelemetry(mcpUrl, client, apiKey) {
             endpoint,
             body,
             attempts: 2,
-            apiKey: resolvedApiKey(apiKey),
+            apiKey: resolvedApiKey(opts?.apiKey),
             label: "connect",
         });
     }
@@ -279,6 +292,8 @@ function createConnectTelemetry(mcpUrl, client, apiKey) {
                 stage,
                 failed_stage: detail?.failedStage,
                 phase: detail?.phase,
+                failure_reason: detail?.failureReason,
+                harness_version: detail?.harnessVersion,
                 runtime_platform: process.platform,
                 node_version: process.version,
                 cli_version: CLI_VERSION,
@@ -296,19 +311,32 @@ function requireCommandSupport(client) {
         timeout: NON_INTERACTIVE_TIMEOUT_MS,
     });
     if (commandNotFound(result.error)) {
-        throw new Error(`${client.displayName} is not installed or not available on PATH.`, {
-            cause: result.error,
-        });
+        throw new PrerequisiteError(`${client.displayName} is not installed or not available on PATH.`, "harness_not_installed", { cause: result.error });
     }
     if (result.error || result.status !== 0) {
         throwIfInterrupted(result);
-        throw new Error(client.supportCheck.unavailableMessage, { cause: result.error });
+        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_command_unsupported", { cause: result.error });
     }
     const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
     if (!client.supportCheck.patterns.every((pattern) => pattern.test(output))) {
-        throw new Error(client.supportCheck.unavailableMessage);
+        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_too_old", {
+            harnessVersion: probeHarnessVersion(client.command),
+        });
     }
 }
+/** Best-effort; the server rejects non-printable characters and >32 chars. */
+function probeHarnessVersion(command) {
+    const result = spawn.sync(command, ["--version"], {
+        encoding: "utf8",
+        timeout: NON_INTERACTIVE_TIMEOUT_MS,
+    });
+    if (result.error || result.status !== 0)
+        return undefined;
+    const version = sanitizeLine(result.stdout ?? "")
+        .replace(/[^\x20-\x7E]/g, "")
+        .trim();
+    return version ? version.slice(0, 32) : undefined;
+}
 function commandNotFound(error) {
     return error?.code === "ENOENT";
 }
@@ -530,7 +558,7 @@ function launchOpenClawWalkthrough() {
     return true;
 }
 async function connectNativeMcpClient(client, options) {
-    const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient, options.apiKey);
+    const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient, options);
     const state = { stage: "prerequisite_check", settled: false };
     await runGuarded(state, telemetry, () => {
         telemetry.track("started");
@@ -580,6 +608,22 @@ async function connectNativeMcpClient(client, options) {
             }
             telemetry.track("checkpoint", { phase: "oauth_done" });
         }
+        // Registration/OAuth make MCP work; later steps are cosmetic and must not fail the attempt.
+        settle(state, telemetry, "completed");
+        runPostInstallSteps(client, options, state, telemetry, useKeyAuth);
+    });
+}
+function connectedLine(client, useKeyAuth) {
+    // Deferred OAuth (codex/hermes): the CLI never observes auth, so don't claim "connected".
+    if (!client.loginArgs && !useKeyAuth) {
+        return (`TinyFish is configured in ${client.displayName}. ${client.displayName} will ask you ` +
+            "to sign in to TinyFish the first time you use it.");
+    }
+    return `TinyFish is connected. Open ${client.displayName} to start using it.`;
+}
+// Runs after `completed` settled: failures warn and report post_install_failed, exit 0.
+function runPostInstallSteps(client, options, state, telemetry, useKeyAuth) {
+    try {
         state.stage = "cli_install";
         installTinyFishCli();
         telemetry.track("checkpoint", { phase: "cli_installed" });
@@ -596,15 +640,24 @@ async function connectNativeMcpClient(client, options) {
         if (client.postConnectNote)
             errLine(client.postConnectNote);
         if (!options.launch) {
-            errLine(`TinyFish is connected. Open ${client.displayName} to start using it.`);
-            settle(state, telemetry, "completed");
+            errLine(connectedLine(client, useKeyAuth));
             return;
         }
         state.stage = "walkthrough_launch";
-        // Install already done; walkthrough Ctrl+C still counts completed.
         launchNativeMcpClient(client);
-        settle(state, telemetry, "completed");
-    });
+    }
+    catch (error) {
+        reportPostInstallFailure(client.connectClient, client.displayName, state, telemetry, error);
+    }
+}
+/** Warn + report post_install_failed; interrupts are abandonment, not failure. */
+function reportPostInstallFailure(connectClient, displayName, state, telemetry, error) {
+    if (!(error instanceof ConnectInterruptedError)) {
+        telemetry.track("post_install_failed", { failedStage: state.stage });
+        errLine(`The ${displayName} MCP connection succeeded, but a finishing step ` +
+            `(${state.stage}) failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    errLine(`Finish setup with: npx -y @tiny-fish/cli@latest connect ${connectClient}`);
 }
 export async function connectClaudeCode(options) {
     await connectNativeMcpClient(CLAUDE_CODE, options);
@@ -619,7 +672,7 @@ export async function connectOpencode(options) {
     await connectNativeMcpClient(OPENCODE, options);
 }
 export async function connectOpenClaw(options) {
-    const telemetry = createConnectTelemetry(options.mcpUrl, "openclaw");
+    const telemetry = createConnectTelemetry(options.mcpUrl, "openclaw", options);
     const state = { stage: "prerequisite_check", settled: false };
     await runGuarded(state, telemetry, () => {
         telemetry.track("started");
@@ -668,20 +721,24 @@ export async function connectOpenClaw(options) {
         telemetry.track("checkpoint", { phase: "authenticated" });
         saveConnectContext("openclaw", telemetry.attemptId);
         errLine(UPGRADE_HINT);
+        // For openclaw the skill install and auth ARE functional; only the walkthrough is cosmetic.
+        settle(state, telemetry, "completed");
         if (!options.launch) {
             errLine("TinyFish is connected. Open OpenClaw to start using it.");
-            settle(state, telemetry, "completed");
             return;
         }
         state.stage = "walkthrough_launch";
-        // Install already done; walkthrough Ctrl+C still counts completed.
-        launchOpenClawWalkthrough();
-        settle(state, telemetry, "completed");
+        try {
+            launchOpenClawWalkthrough();
+        }
+        catch (error) {
+            reportPostInstallFailure("openclaw", "OpenClaw", state, telemetry, error);
+        }
     });
 }
 /** Writes mcp.json directly — no `cursor mcp add` exists. */
 export async function connectCursor(options) {
-    const telemetry = createConnectTelemetry(options.mcpUrl, "cursor", options.apiKey);
+    const telemetry = createConnectTelemetry(options.mcpUrl, "cursor", options);
     const state = { stage: "prerequisite_check", settled: false };
     await runGuarded(state, telemetry, async () => {
         telemetry.track("started");
@@ -784,7 +841,7 @@ export function registerConnect(program) {
         if (options.apiKey && !validateKeyFormat(options.apiKey)) {
             throw new Error("Invalid --api-key value");
         }
-        const mcpUrl = options.url ?? DEFAULT_MCP_URL;
+        let mcpUrl = options.url ?? DEFAULT_MCP_URL;
         if (mcpUrl.startsWith("-")) {
             throw new Error(`Invalid --url value: ${mcpUrl}`);
         }
@@ -798,6 +855,16 @@ export function registerConnect(program) {
         if (!["http:", "https:"].includes(parsedUrl.protocol)) {
             throw new Error(`Invalid --url value: ${mcpUrl}`);
         }
+        // Page-minted attempt id rides in on --url. Strip before the URL becomes the MCP
+        // base — registration re-stamps it, and nothing else may carry it.
+        const pageAttemptId = parsedUrl.searchParams.get("connect_attempt_id");
+        let attemptId;
+        if (pageAttemptId !== null) {
+            parsedUrl.searchParams.delete("connect_attempt_id");
+            mcpUrl = parsedUrl.toString();
+            if (z.uuid().safeParse(pageAttemptId).success)
+                attemptId = pageAttemptId;
+        }
         if (options.all) {
             if (client) {
                 throw new Error("Pass either a client or --all, not both.");
@@ -823,7 +890,12 @@ export function registerConnect(program) {
         if (!client) {
             throw new Error("Pass a client (claude-code, codex, cursor, hermes, openclaw) or --all.");
         }
-        const connectOptions = { apiKey: options.apiKey, mcpUrl, launch: options.launch ?? false };
+        const connectOptions = {
+            apiKey: options.apiKey,
+            mcpUrl,
+            launch: options.launch ?? false,
+            attemptId,
+        };
         if (client === "claude-code") {
             await connectClaudeCode(connectOptions);
         }
@@ -837,12 +909,12 @@ export function registerConnect(program) {
             await connectOpencode(connectOptions);
         }
         else if (client === "openclaw") {
-            await connectOpenClaw({ mcpUrl: connectOptions.mcpUrl, launch: connectOptions.launch });
+            await connectOpenClaw(connectOptions);
         }
         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 });
+            await connectCursor(connectOptions);
             if (connectOptions.launch) {
                 errLine("Cursor has no launchable walkthrough. Open Cursor and start chatting.");
             }

package/dist/lib/harness.js

@@ -3,7 +3,7 @@
 // value (unenumerated, lowercase-kebab, matching MCP client_name like
 // "claude-code"). Explicit TF_CLIENT_NAME always wins upstream in client.ts.
 //
-// Fingerprints verified by running scripts/harness-probe against each harness.
+// Fingerprints verified by running scripts/harness-probe.mjs (repo root) in each harness.
 // Order matters: wrappers that embed another agent must precede the embedded
 // one. OpenClaw drives Claude Code via `sdk-cli`, so its env carries both
 // CLAUDECODE=1 and OPENCLAW_MCP_*; it must be checked before claude-code.
@@ -21,9 +21,7 @@ const HARNESS_FINGERPRINTS = [
     // prefix so we catch a Codex run regardless of which of its vars are set.
     { name: "codex", matches: (env) => hasVarWithPrefix(env, "CODEX_") },
     { name: "hermes", matches: (env) => hasVarWithPrefix(env, "HERMES_") },
-    // OpenCode sets a bare `OPENCODE` env var globally at startup (opencode#9292), inherited by
-    // the commands it shells out. Exact key, not a prefix — `OPENCODE_*` are user config inputs.
-    // Sourced from OpenCode's docs, not yet confirmed against scripts/harness-probe.
+    // Exact key, not a prefix: opencode writes OPENCODE=1 at startup, reads every OPENCODE_* as config.
     { name: "opencode", matches: (env) => Boolean(env["OPENCODE"]) },
     {
         name: "claude-code",

package/package.json

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