@tiny-fish/cli 0.19.1-next.175 → 0.19.1-next.178

package/dist/commands/connect.d.ts

@@ -1,12 +1,7 @@
 import { Command } from "commander";
+import { type AgentClient } from "../lib/connect-runtime.js";
 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" | "cursor" | "hermes" | "openclaw" | "opencode";
-/** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
-export declare class ConnectInterruptedError extends Error {
-}
 interface NativeConnectOptions {
     apiKey?: string;
     mcpUrl: string;

package/dist/commands/connect.js

@@ -1,55 +1,18 @@
-import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import spawn from "cross-spawn";
-import { CONNECT_ATTEMPT_ENV, CONNECT_SOURCE, isAttemptId, loadConfig, persistApiKeyToEnvironment, resolvedApiKey, saveConnectContext, takePendingConnectAttempt, validateKeyFormat, validatedApiKey, writeConfig, } from "../lib/auth.js";
-import { CLI_VERSION, TINYFISH_CLI_PACKAGE } from "../lib/constants.js";
+import { CONNECT_SOURCE, loadConfig, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, validatedApiKey, writeConfig, } from "../lib/auth.js";
+import { CLAUDE_CODE, CODEX, HERMES, OPENCLAW, OPENCLAW_SKILL_INSTALL_ARGS, OPENCODE, launchNativeMcpClient, launchOpenClawWalkthrough, } from "../lib/connect-clients.js";
+import { commandNotFound, ConnectInterruptedError, createConnectTelemetry, requireCommandSupport, runGuarded, settle, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "../lib/connect-runtime.js";
+import { TINYFISH_CLI_PACKAGE } from "../lib/constants.js";
 import { cursorInstallDeeplink, cursorMcpPath, writeCursorMcpConfig, } from "../lib/cursor-config.js";
 import { runConnectAll } from "../lib/connect-all.js";
 import { detectHumanInitiated } from "../lib/harness.js";
 import { emitNotice } from "../lib/notice.js";
-import { errLine, sanitizeLine } from "../lib/output.js";
-import { codexOauthCompleted } from "../lib/registration-detect.js";
+import { errLine } 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";
 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;
-// An old install is only one reason a flag can go unseen, so no message asserts the cause.
-const SUPPORT_CHECK_DEBUG_HINT = " Set TINYFISH_DEBUG=1 and retry to print the help output TinyFish read.";
-const MCP_ADD_UNAVAILABLE_MESSAGE = "Could not confirm this Claude Code installation exposes `claude mcp add`: `claude mcp " +
-    "--help` did not list it. Update Claude Code with `claude update` and retry." +
-    SUPPORT_CHECK_DEBUG_HINT;
-// `claude mcp login` only exists upstream from Claude Code 2.1.186; older installs still register.
-const CLAUDE_CODE_KEYED_FALLBACK_NOTE = "Using your stored TinyFish API key: this Claude Code predates one-command sign-in " +
-    "(`claude mcp login`), so no browser sign-in is needed.";
-const CLAUDE_CODE_DEFERRED_AUTH_NOTE = "TinyFish is registered in Claude Code but not signed in: this Claude Code predates " +
-    "one-command sign-in (`claude mcp login`). Open Claude Code and run `/mcp` to sign in to " +
-    "TinyFish. `claude update` gets you one-command sign-in.";
-const CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE = "Could not confirm this Codex installation supports one-command MCP authentication: `codex " +
-    "mcp add --help` did not list `--oauth-resource`. Update Codex and retry, or add TinyFish " +
-    "manually with `codex mcp add`." +
-    SUPPORT_CHECK_DEBUG_HINT;
-const HERMES_OAUTH_UNAVAILABLE_MESSAGE = "Could not confirm this Hermes installation supports one-command MCP authentication: `hermes " +
-    "mcp add --help` did not list `--auth oauth`. Update Hermes and retry, or add TinyFish " +
-    "manually with `hermes mcp add`." +
-    SUPPORT_CHECK_DEBUG_HINT;
-const OPENCLAW_SKILL_UNAVAILABLE_MESSAGE = "Could not confirm this OpenClaw installation supports global skill installation: `openclaw " +
-    "skills install --help` did not list `--global` and `--acknowledge-clawhub-risk`. Update " +
-    "OpenClaw and retry, or install manually with `openclaw skills install @tinyfish/tinyfish " +
-    "--global --acknowledge-clawhub-risk`." +
-    SUPPORT_CHECK_DEBUG_HINT;
-const OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE = "Could not confirm this OpenCode installation supports one-command MCP setup: `opencode mcp " +
-    "add --help` did not list `--url`. Update OpenCode and retry, or add TinyFish manually with " +
-    "`opencode mcp add`." +
-    SUPPORT_CHECK_DEBUG_HINT;
-// OpenCode is model-agnostic (unlike Claude Code / Codex), so a fresh install can default to a
-// model with no tool support — TinyFish runs entirely on tool calls, so it would fail there.
-const OPENCODE_MODEL_NOTE = "Note: TinyFish runs on tool calls, so OpenCode needs a model that supports tool use. Image-only " +
-    'models (e.g. Nano Banana Pro) will show "No endpoints found that support tool use" — switch ' +
-    "OpenCode's model if the walkthrough can't start.";
 const TINYFISH_CLI_NOT_FOUND_MESSAGE = "TinyFish CLI installed but is not available on PATH. Open a new terminal and retry.";
 const TINYFISH_CLI_INSTALL_SPEC = `${TINYFISH_CLI_PACKAGE}@latest`;
 export const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI and skill.";
@@ -57,343 +20,6 @@ export const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI a
 const SKILLS_CLI_PACKAGE = "skills@1.5.15";
 const TINYFISH_WEB_SKILL_SOURCE = "tinyfish-io/tinyfish-cookbook";
 const TINYFISH_WEB_SKILL = "use-tinyfish";
-const OPENCLAW_SKILL = "@tinyfish/tinyfish";
-// --force makes this an unconditional overwrite, so the same call installs and refreshes.
-const OPENCLAW_SKILL_INSTALL_ARGS = [
-    "skills",
-    "install",
-    OPENCLAW_SKILL,
-    "--global",
-    "--force",
-    "--acknowledge-clawhub-risk",
-];
-export const DEFAULT_ONBOARDING_PROMPT = "I just connected TinyFish. Call the guide_next_step tool now to begin. Then follow its " +
-    "instructions one step at a time. Ask for my input and wait for my reply before each subsequent " +
-    "TinyFish tool call.";
-export const OPENCLAW_ONBOARDING_PROMPT = "I just installed the TinyFish skill. Guide me through it interactively: first ask what topic I " +
-    "want to search and wait for my reply before using TinyFish Search. Show me the results, ask " +
-    "which result I want to read, and wait before using TinyFish Fetch. Then ask what browser task " +
-    "I want to complete and wait before using TinyFish Agent. Never skip ahead or choose for me.";
-/** 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.
-    if (result.error?.code === "ETIMEDOUT")
-        return;
-    if (result.signal === "SIGINT" || result.signal === "SIGTERM") {
-        throw new ConnectInterruptedError("Setup interrupted");
-    }
-}
-/** Terminal events exactly once, whichever of flow or signal handler wins. */
-function settle(state, telemetry, stage, detail) {
-    if (state.settled)
-        return;
-    state.settled = true;
-    telemetry.track(stage, detail);
-}
-// Raw-mode children still surface via throwIfInterrupted; cooked-mode stages
-// (npm/npx/OAuth waits) land here.
-function installConnectSignalGuard(state, telemetry) {
-    return installSignalGuard(async () => {
-        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, else failed. */
-async function runGuarded(state, telemetry, body) {
-    const uninstallSignalGuard = installConnectSignalGuard(state, telemetry);
-    try {
-        await body();
-    }
-    catch (error) {
-        if (error instanceof ConnectInterruptedError) {
-            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,
-            ...(error instanceof PrerequisiteError
-                ? { failureReason: error.failureReason, harnessVersion: error.harnessVersion }
-                : {}),
-        });
-        throw error;
-    }
-    finally {
-        uninstallSignalGuard();
-        await telemetry.flush();
-    }
-}
-const CLAUDE_CODE = {
-    command: "claude",
-    connectClient: "claude-code",
-    skillAgent: "claude-code",
-    displayName: "Claude Code",
-    supportCheck: {
-        args: ["mcp", "--help"],
-        patterns: [/^\s*add(?:\s|\[)/m],
-        optionalPatterns: [/^\s*login(?:\s|\[)/m],
-        unavailableMessage: MCP_ADD_UNAVAILABLE_MESSAGE,
-    },
-    headerAuthSupported: true,
-    loginArgs: ["mcp", "login", "tinyfish"],
-    degradedAuthNotes: {
-        keyed: CLAUDE_CODE_KEYED_FALLBACK_NOTE,
-        deferred: CLAUDE_CODE_DEFERRED_AUTH_NOTE,
-    },
-    // Project scope is shared in .mcp.json; a user setup command must not rewrite it.
-    removals: [
-        { args: ["mcp", "remove", "tinyfish", "--scope", "user"], label: "user TinyFish registration" },
-        {
-            args: ["mcp", "remove", "tinyfish", "--scope", "local"],
-            label: "local TinyFish registration",
-        },
-    ],
-    addArgs: (mcpUrl) => ["mcp", "add", "--scope", "user", "--transport", "http", "tinyfish", mcpUrl],
-};
-function launchCodexWalkthrough() {
-    const deepLink = new URL("codex://new");
-    deepLink.searchParams.set("prompt", DEFAULT_ONBOARDING_PROMPT);
-    deepLink.searchParams.set("path", process.cwd());
-    const [command, args] = process.platform === "darwin"
-        ? ["open", [deepLink.toString()]]
-        : process.platform === "win32"
-            ? ["cmd", ["/c", "start", "", deepLink.toString()]]
-            : ["xdg-open", [deepLink.toString()]];
-    const result = spawn.sync(command, args, { stdio: "ignore" });
-    if (result.error || result.status !== 0) {
-        throw new Error("Could not open Codex", { cause: result.error });
-    }
-    errLine("Codex opened with the TinyFish walkthrough ready. Send the prompt to start.");
-}
-const CODEX = {
-    command: "codex",
-    connectClient: "codex",
-    skillAgent: "codex",
-    displayName: "Codex",
-    supportCheck: {
-        args: ["mcp", "add", "--help"],
-        patterns: [/--oauth-resource(?:\s|<)/],
-        unavailableMessage: CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE,
-    },
-    launchWalkthrough: launchCodexWalkthrough,
-    probeAuthenticated: codexOauthCompleted,
-    // Retry only: running it after a finished inline OAuth is a second browser hop.
-    loginArgs: ["mcp", "login", "tinyfish"],
-    removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Codex" }],
-    addArgs: (mcpUrl, oauthResource) => [
-        "mcp",
-        "add",
-        "tinyfish",
-        "--url",
-        mcpUrl,
-        "--oauth-resource",
-        oauthResource,
-    ],
-};
-function launchHermesWalkthrough() {
-    const seedResult = spawn.sync("hermes", ["chat", "-Q", "-q", DEFAULT_ONBOARDING_PROMPT], {
-        encoding: "utf8",
-        timeout: HERMES_SEED_TIMEOUT_MS,
-    });
-    if (seedResult.error || seedResult.status !== 0) {
-        throwIfInterrupted(seedResult);
-        throw new Error("Could not start the TinyFish walkthrough in Hermes", {
-            cause: seedResult.error,
-        });
-    }
-    // A colourised id would carry its trailing escape sequence into `--resume` (PF-3452).
-    const sessionId = sanitizeLine(seedResult.stderr ?? "").match(/session_id:\s*([^\s]+)/i)?.[1];
-    if (!sessionId) {
-        throw new Error("Hermes did not return a walkthrough session ID");
-    }
-    const result = spawn.sync("hermes", ["--resume", sessionId], { stdio: "inherit" });
-    if (result.error) {
-        throw new Error("Could not launch Hermes", { cause: result.error });
-    }
-    if (result.signal === "SIGINT" || result.signal === "SIGTERM")
-        return;
-    if (result.status !== 0) {
-        throw new Error(`Hermes walkthrough exited with status ${result.status ?? "unknown"}`);
-    }
-}
-const HERMES = {
-    command: "hermes",
-    connectClient: "hermes",
-    skillAgent: "hermes-agent",
-    displayName: "Hermes",
-    supportCheck: {
-        args: ["mcp", "add", "--help"],
-        patterns: [/--auth\s+\{[^}]*oauth[^}]*\}/],
-        unavailableMessage: HERMES_OAUTH_UNAVAILABLE_MESSAGE,
-    },
-    removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Hermes" }],
-    // Hermes completes OAuth while adding the server; a separate `mcp login` would authenticate twice.
-    addArgs: (mcpUrl) => ["mcp", "add", "tinyfish", "--url", mcpUrl, "--auth", "oauth"],
-    launchWalkthrough: launchHermesWalkthrough,
-};
-// OpenCode's TUI takes a positional as a project directory, so a bare `opencode "<prompt>"`
-// would be read as a folder. The `--prompt` flag seeds the interactive TUI with a first message
-// (opencode.ai/docs/cli), so the onboarding guide fires just like the other agents.
-function launchOpencode() {
-    const result = spawn.sync("opencode", ["--prompt", DEFAULT_ONBOARDING_PROMPT], {
-        stdio: "inherit",
-    });
-    if (result.error) {
-        throw new Error("Could not launch OpenCode", { cause: result.error });
-    }
-    if (result.signal === "SIGINT" || result.signal === "SIGTERM")
-        return;
-    if (result.status !== 0) {
-        throw new Error(`OpenCode exited with status ${result.status ?? "unknown"}`);
-    }
-}
-const OPENCODE = {
-    command: "opencode",
-    connectClient: "opencode",
-    skillAgent: "opencode",
-    displayName: "OpenCode",
-    supportCheck: {
-        args: ["mcp", "add", "--help"],
-        patterns: [/--url(?:\s|$)/m],
-        unavailableMessage: OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE,
-    },
-    // `opencode mcp add` upserts by name and there is no `opencode mcp remove`, so no cleanup step.
-    removals: [],
-    // OpenCode writes ~/.config/opencode/opencode.jsonc itself; `mcp auth` is the separate OAuth step.
-    addArgs: (mcpUrl) => ["mcp", "add", "tinyfish", "--url", mcpUrl],
-    loginArgs: ["mcp", "auth", "tinyfish"],
-    launchWalkthrough: launchOpencode,
-    postConnectNote: OPENCODE_MODEL_NOTE,
-};
-const OPENCLAW = {
-    command: "openclaw",
-    displayName: "OpenClaw",
-    supportCheck: {
-        args: ["skills", "install", "--help"],
-        patterns: [/--global(?:\s|$)/, /--acknowledge-clawhub-risk(?:\s|$)/],
-        unavailableMessage: OPENCLAW_SKILL_UNAVAILABLE_MESSAGE,
-    },
-};
-/**
- * One page-minted id seeds one install attempt, so `tinyfish onboard` connecting three agents
- * does not report three installs under it. Later connects in the run fall back to a random id.
- */
-function takeSeedAttemptId() {
-    const fromEnv = process.env[CONNECT_ATTEMPT_ENV];
-    // Both sources are read-and-clear, and the delete lands before any subprocess inherits it.
-    delete process.env[CONNECT_ATTEMPT_ENV];
-    const parked = takePendingConnectAttempt();
-    return fromEnv && isAttemptId(fromEnv) ? fromEnv : parked;
-}
-function createConnectTelemetry(mcpUrl, client, opts) {
-    // Consumed even when --url already supplied an id: leaving it behind would let a stale
-    // seed reach the agent this connect launches, or the next connect on this machine.
-    const seeded = takeSeedAttemptId();
-    // A setup-page id (via --url, the env var, or one parked by login) joins "copied the
-    // command" to this install attempt.
-    const attemptId = opts?.attemptId ?? seeded ?? randomUUID();
-    const endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
-    const pending = [];
-    async function deliver(body) {
-        // Ahead of the key read; postConnectEvent's own opt-out check is too late to skip it.
-        if (telemetryDisabled())
-            return;
-        // Resolved per event: `tinyfish auth login` writes the config from a subprocess mid-connect.
-        await postConnectEvent({
-            endpoint,
-            body,
-            attempts: 2,
-            apiKey: resolvedApiKey(opts?.apiKey),
-            label: "connect",
-        });
-    }
-    return {
-        attemptId,
-        // Fire-and-forget; awaiting each event stalls setup when telemetry down.
-        track(stage, detail) {
-            pending.push(deliver(JSON.stringify({
-                attempt_id: attemptId,
-                client,
-                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,
-                // Same signal the usage events carry, so TTY and headless connects can be split.
-                is_human_initiated: detectHumanInitiated(),
-            })));
-        },
-        // Awaited in finally so in-flight events land before exit.
-        async flush() {
-            await Promise.all(pending);
-        },
-    };
-}
-function requireCommandSupport(client) {
-    const result = spawn.sync(client.command, client.supportCheck.args, {
-        encoding: "utf8",
-        // Agent harnesses export FORCE_COLOR, which makes clients colourise even a piped --help.
-        env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
-        timeout: NON_INTERACTIVE_TIMEOUT_MS,
-    });
-    if (commandNotFound(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 PrerequisiteError(client.supportCheck.unavailableMessage, "harness_command_unsupported", { cause: result.error });
-    }
-    // Belt and braces with the colour env: a client that ignores NO_COLOR still has to match.
-    const output = sanitizeLine(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
-    const listed = (patterns) => patterns.every((pattern) => pattern.test(output));
-    const essential = listed(client.supportCheck.patterns);
-    const optionalSupported = listed(client.supportCheck.optionalPatterns ?? []);
-    if ((!essential || !optionalSupported) && process.env["TINYFISH_DEBUG"]) {
-        errLine(`${client.command} ${client.supportCheck.args.join(" ")} printed:\n${output.trim()}`);
-    }
-    if (!essential) {
-        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_too_old", {
-            harnessVersion: probeHarnessVersion(client.command),
-        });
-    }
-    return { optionalSupported };
-}
-/** 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";
-}
 export function installTinyFishCli() {
     errLine("Installing the TinyFish CLI...");
     const result = spawn.sync("npm", ["install", "--global", TINYFISH_CLI_INSTALL_SPEC], {
@@ -579,38 +205,6 @@ function removeExistingRegistration(client, removal) {
     }
     throw new Error(`Could not remove existing ${removal.label}: ${details}`);
 }
-function launchNativeMcpClient(client) {
-    errLine(`Starting the TinyFish walkthrough in ${client.displayName}...`);
-    if (client.launchWalkthrough) {
-        client.launchWalkthrough();
-        return true;
-    }
-    const result = spawn.sync(client.command, [DEFAULT_ONBOARDING_PROMPT], { stdio: "inherit" });
-    if (result.error) {
-        throw new Error(`Could not launch ${client.displayName}`, { cause: result.error });
-    }
-    if (result.signal === "SIGINT" || result.signal === "SIGTERM")
-        return false;
-    if (result.status !== 0) {
-        throw new Error(`${client.displayName} walkthrough exited with status ${result.status ?? "unknown"}`);
-    }
-    return true;
-}
-function launchOpenClawWalkthrough() {
-    errLine("Starting the TinyFish walkthrough in OpenClaw...");
-    const result = spawn.sync("openclaw", ["chat", "--message", OPENCLAW_ONBOARDING_PROMPT], {
-        stdio: "inherit",
-    });
-    if (result.error) {
-        throw new Error("Could not launch OpenClaw", { cause: result.error });
-    }
-    if (result.signal === "SIGINT" || result.signal === "SIGTERM")
-        return false;
-    if (result.status !== 0) {
-        throw new Error(`OpenClaw walkthrough exited with status ${result.status ?? "unknown"}`);
-    }
-    return true;
-}
 async function connectNativeMcpClient(client, options) {
     const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient, options);
     const state = { stage: "prerequisite_check", settled: false };

package/dist/commands/upgrade.js

@@ -5,7 +5,8 @@ import { suppressNotice } from "../lib/notice.js";
 import { errLine } from "../lib/output.js";
 import { sendUpgradeCompleted, telemetryDisabled, } from "../lib/setup-telemetry.js";
 import { installSignalGuard, SIGNAL_EXIT_CODES } from "../lib/signals.js";
-import { ConnectInterruptedError, installTinyFishCli, updateWebSkill } from "./connect.js";
+import { ConnectInterruptedError } from "../lib/connect-runtime.js";
+import { installTinyFishCli, updateWebSkill } from "./connect.js";
 const VERSION_READ_TIMEOUT_MS = 2_000;
 const INTERRUPTED_MESSAGE = "Upgrade interrupted — run `tinyfish upgrade` again to finish.";
 function attempt(label, run) {

package/dist/lib/connect-clients.d.ts

@@ -0,0 +1,33 @@
+import { type AgentClient, type SupportedCommand } from "./connect-runtime.js";
+export declare const OPENCLAW_SKILL_INSTALL_ARGS: readonly string[];
+export declare const DEFAULT_ONBOARDING_PROMPT: string;
+export declare const OPENCLAW_ONBOARDING_PROMPT: string;
+export interface NativeMcpClient extends SupportedCommand {
+    connectClient: Exclude<AgentClient, "openclaw">;
+    skillAgent: "claude-code" | "codex" | "hermes-agent" | "opencode";
+    /** `mcp add --header` support: a stored TinyFish key replaces the OAuth login. */
+    headerAuthSupported?: boolean;
+    loginArgs?: string[];
+    /** Replaces the `loginArgs` step when `supportCheck.optionalPatterns` miss. */
+    degradedAuthNotes?: {
+        keyed: string;
+        deferred: string;
+    };
+    /** Did the OAuth inside `mcp add` finish? undefined when the client cannot say. */
+    probeAuthenticated?: () => boolean | undefined;
+    removals: {
+        args: string[];
+        label: string;
+    }[];
+    addArgs: (mcpUrl: string, oauthResource: string) => string[];
+    launchWalkthrough?: () => void;
+    /** Printed after a successful connect, on both the launch and non-launch paths. */
+    postConnectNote?: string;
+}
+export declare const CLAUDE_CODE: NativeMcpClient;
+export declare const CODEX: NativeMcpClient;
+export declare const HERMES: NativeMcpClient;
+export declare const OPENCODE: NativeMcpClient;
+export declare const OPENCLAW: SupportedCommand;
+export declare function launchNativeMcpClient(client: NativeMcpClient): boolean;
+export declare function launchOpenClawWalkthrough(): boolean;

package/dist/lib/connect-clients.js

@@ -0,0 +1,238 @@
+import spawn from "cross-spawn";
+import { errLine, sanitizeLine } from "./output.js";
+import { throwIfInterrupted } from "./connect-runtime.js";
+import { codexOauthCompleted } from "./registration-detect.js";
+const HERMES_SEED_TIMEOUT_MS = 120_000;
+// An old install is only one reason a flag can go unseen, so no message asserts the cause.
+const SUPPORT_CHECK_DEBUG_HINT = " Set TINYFISH_DEBUG=1 and retry to print the help output TinyFish read.";
+const MCP_ADD_UNAVAILABLE_MESSAGE = "Could not confirm this Claude Code installation exposes `claude mcp add`: `claude mcp " +
+    "--help` did not list it. Update Claude Code with `claude update` and retry." +
+    SUPPORT_CHECK_DEBUG_HINT;
+// `claude mcp login` only exists upstream from Claude Code 2.1.186; older installs still register.
+const CLAUDE_CODE_KEYED_FALLBACK_NOTE = "Using your stored TinyFish API key: this Claude Code predates one-command sign-in " +
+    "(`claude mcp login`), so no browser sign-in is needed.";
+const CLAUDE_CODE_DEFERRED_AUTH_NOTE = "TinyFish is registered in Claude Code but not signed in: this Claude Code predates " +
+    "one-command sign-in (`claude mcp login`). Open Claude Code and run `/mcp` to sign in to " +
+    "TinyFish. `claude update` gets you one-command sign-in.";
+const CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE = "Could not confirm this Codex installation supports one-command MCP authentication: `codex " +
+    "mcp add --help` did not list `--oauth-resource`. Update Codex and retry, or add TinyFish " +
+    "manually with `codex mcp add`." +
+    SUPPORT_CHECK_DEBUG_HINT;
+const HERMES_OAUTH_UNAVAILABLE_MESSAGE = "Could not confirm this Hermes installation supports one-command MCP authentication: `hermes " +
+    "mcp add --help` did not list `--auth oauth`. Update Hermes and retry, or add TinyFish " +
+    "manually with `hermes mcp add`." +
+    SUPPORT_CHECK_DEBUG_HINT;
+const OPENCLAW_SKILL_UNAVAILABLE_MESSAGE = "Could not confirm this OpenClaw installation supports global skill installation: `openclaw " +
+    "skills install --help` did not list `--global` and `--acknowledge-clawhub-risk`. Update " +
+    "OpenClaw and retry, or install manually with `openclaw skills install @tinyfish/tinyfish " +
+    "--global --acknowledge-clawhub-risk`." +
+    SUPPORT_CHECK_DEBUG_HINT;
+const OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE = "Could not confirm this OpenCode installation supports one-command MCP setup: `opencode mcp " +
+    "add --help` did not list `--url`. Update OpenCode and retry, or add TinyFish manually with " +
+    "`opencode mcp add`." +
+    SUPPORT_CHECK_DEBUG_HINT;
+// OpenCode is model-agnostic (unlike Claude Code / Codex), so a fresh install can default to a
+// model with no tool support — TinyFish runs entirely on tool calls, so it would fail there.
+const OPENCODE_MODEL_NOTE = "Note: TinyFish runs on tool calls, so OpenCode needs a model that supports tool use. Image-only " +
+    'models (e.g. Nano Banana Pro) will show "No endpoints found that support tool use" — switch ' +
+    "OpenCode's model if the walkthrough can't start.";
+const OPENCLAW_SKILL = "@tinyfish/tinyfish";
+// --force makes this an unconditional overwrite, so the same call installs and refreshes.
+export const OPENCLAW_SKILL_INSTALL_ARGS = [
+    "skills",
+    "install",
+    OPENCLAW_SKILL,
+    "--global",
+    "--force",
+    "--acknowledge-clawhub-risk",
+];
+export const DEFAULT_ONBOARDING_PROMPT = "I just connected TinyFish. Call the guide_next_step tool now to begin. Then follow its " +
+    "instructions one step at a time. Ask for my input and wait for my reply before each subsequent " +
+    "TinyFish tool call.";
+export const OPENCLAW_ONBOARDING_PROMPT = "I just installed the TinyFish skill. Guide me through it interactively: first ask what topic I " +
+    "want to search and wait for my reply before using TinyFish Search. Show me the results, ask " +
+    "which result I want to read, and wait before using TinyFish Fetch. Then ask what browser task " +
+    "I want to complete and wait before using TinyFish Agent. Never skip ahead or choose for me.";
+export const CLAUDE_CODE = {
+    command: "claude",
+    connectClient: "claude-code",
+    skillAgent: "claude-code",
+    displayName: "Claude Code",
+    supportCheck: {
+        args: ["mcp", "--help"],
+        patterns: [/^\s*add(?:\s|\[)/m],
+        optionalPatterns: [/^\s*login(?:\s|\[)/m],
+        unavailableMessage: MCP_ADD_UNAVAILABLE_MESSAGE,
+    },
+    headerAuthSupported: true,
+    loginArgs: ["mcp", "login", "tinyfish"],
+    degradedAuthNotes: {
+        keyed: CLAUDE_CODE_KEYED_FALLBACK_NOTE,
+        deferred: CLAUDE_CODE_DEFERRED_AUTH_NOTE,
+    },
+    // Project scope is shared in .mcp.json; a user setup command must not rewrite it.
+    removals: [
+        { args: ["mcp", "remove", "tinyfish", "--scope", "user"], label: "user TinyFish registration" },
+        {
+            args: ["mcp", "remove", "tinyfish", "--scope", "local"],
+            label: "local TinyFish registration",
+        },
+    ],
+    addArgs: (mcpUrl) => ["mcp", "add", "--scope", "user", "--transport", "http", "tinyfish", mcpUrl],
+};
+function launchCodexWalkthrough() {
+    const deepLink = new URL("codex://new");
+    deepLink.searchParams.set("prompt", DEFAULT_ONBOARDING_PROMPT);
+    deepLink.searchParams.set("path", process.cwd());
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [deepLink.toString()]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", deepLink.toString()]]
+            : ["xdg-open", [deepLink.toString()]];
+    const result = spawn.sync(command, args, { stdio: "ignore" });
+    if (result.error || result.status !== 0) {
+        throw new Error("Could not open Codex", { cause: result.error });
+    }
+    errLine("Codex opened with the TinyFish walkthrough ready. Send the prompt to start.");
+}
+export const CODEX = {
+    command: "codex",
+    connectClient: "codex",
+    skillAgent: "codex",
+    displayName: "Codex",
+    supportCheck: {
+        args: ["mcp", "add", "--help"],
+        patterns: [/--oauth-resource(?:\s|<)/],
+        unavailableMessage: CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE,
+    },
+    launchWalkthrough: launchCodexWalkthrough,
+    probeAuthenticated: codexOauthCompleted,
+    // Retry only: running it after a finished inline OAuth is a second browser hop.
+    loginArgs: ["mcp", "login", "tinyfish"],
+    removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Codex" }],
+    addArgs: (mcpUrl, oauthResource) => [
+        "mcp",
+        "add",
+        "tinyfish",
+        "--url",
+        mcpUrl,
+        "--oauth-resource",
+        oauthResource,
+    ],
+};
+function launchHermesWalkthrough() {
+    const seedResult = spawn.sync("hermes", ["chat", "-Q", "-q", DEFAULT_ONBOARDING_PROMPT], {
+        encoding: "utf8",
+        timeout: HERMES_SEED_TIMEOUT_MS,
+    });
+    if (seedResult.error || seedResult.status !== 0) {
+        throwIfInterrupted(seedResult);
+        throw new Error("Could not start the TinyFish walkthrough in Hermes", {
+            cause: seedResult.error,
+        });
+    }
+    // A colourised id would carry its trailing escape sequence into `--resume` (PF-3452).
+    const sessionId = sanitizeLine(seedResult.stderr ?? "").match(/session_id:\s*([^\s]+)/i)?.[1];
+    if (!sessionId) {
+        throw new Error("Hermes did not return a walkthrough session ID");
+    }
+    const result = spawn.sync("hermes", ["--resume", sessionId], { stdio: "inherit" });
+    if (result.error) {
+        throw new Error("Could not launch Hermes", { cause: result.error });
+    }
+    if (result.signal === "SIGINT" || result.signal === "SIGTERM")
+        return;
+    if (result.status !== 0) {
+        throw new Error(`Hermes walkthrough exited with status ${result.status ?? "unknown"}`);
+    }
+}
+export const HERMES = {
+    command: "hermes",
+    connectClient: "hermes",
+    skillAgent: "hermes-agent",
+    displayName: "Hermes",
+    supportCheck: {
+        args: ["mcp", "add", "--help"],
+        patterns: [/--auth\s+\{[^}]*oauth[^}]*\}/],
+        unavailableMessage: HERMES_OAUTH_UNAVAILABLE_MESSAGE,
+    },
+    removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Hermes" }],
+    // Hermes completes OAuth while adding the server; a separate `mcp login` would authenticate twice.
+    addArgs: (mcpUrl) => ["mcp", "add", "tinyfish", "--url", mcpUrl, "--auth", "oauth"],
+    launchWalkthrough: launchHermesWalkthrough,
+};
+// OpenCode's TUI takes a positional as a project directory, so a bare `opencode "<prompt>"`
+// would be read as a folder. The `--prompt` flag seeds the interactive TUI with a first message
+// (opencode.ai/docs/cli), so the onboarding guide fires just like the other agents.
+function launchOpencode() {
+    const result = spawn.sync("opencode", ["--prompt", DEFAULT_ONBOARDING_PROMPT], {
+        stdio: "inherit",
+    });
+    if (result.error) {
+        throw new Error("Could not launch OpenCode", { cause: result.error });
+    }
+    if (result.signal === "SIGINT" || result.signal === "SIGTERM")
+        return;
+    if (result.status !== 0) {
+        throw new Error(`OpenCode exited with status ${result.status ?? "unknown"}`);
+    }
+}
+export const OPENCODE = {
+    command: "opencode",
+    connectClient: "opencode",
+    skillAgent: "opencode",
+    displayName: "OpenCode",
+    supportCheck: {
+        args: ["mcp", "add", "--help"],
+        patterns: [/--url(?:\s|$)/m],
+        unavailableMessage: OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE,
+    },
+    // `opencode mcp add` upserts by name and there is no `opencode mcp remove`, so no cleanup step.
+    removals: [],
+    // OpenCode writes ~/.config/opencode/opencode.jsonc itself; `mcp auth` is the separate OAuth step.
+    addArgs: (mcpUrl) => ["mcp", "add", "tinyfish", "--url", mcpUrl],
+    loginArgs: ["mcp", "auth", "tinyfish"],
+    launchWalkthrough: launchOpencode,
+    postConnectNote: OPENCODE_MODEL_NOTE,
+};
+export const OPENCLAW = {
+    command: "openclaw",
+    displayName: "OpenClaw",
+    supportCheck: {
+        args: ["skills", "install", "--help"],
+        patterns: [/--global(?:\s|$)/, /--acknowledge-clawhub-risk(?:\s|$)/],
+        unavailableMessage: OPENCLAW_SKILL_UNAVAILABLE_MESSAGE,
+    },
+};
+export function launchNativeMcpClient(client) {
+    errLine(`Starting the TinyFish walkthrough in ${client.displayName}...`);
+    if (client.launchWalkthrough) {
+        client.launchWalkthrough();
+        return true;
+    }
+    const result = spawn.sync(client.command, [DEFAULT_ONBOARDING_PROMPT], { stdio: "inherit" });
+    if (result.error) {
+        throw new Error(`Could not launch ${client.displayName}`, { cause: result.error });
+    }
+    if (result.signal === "SIGINT" || result.signal === "SIGTERM")
+        return false;
+    if (result.status !== 0) {
+        throw new Error(`${client.displayName} walkthrough exited with status ${result.status ?? "unknown"}`);
+    }
+    return true;
+}
+export function launchOpenClawWalkthrough() {
+    errLine("Starting the TinyFish walkthrough in OpenClaw...");
+    const result = spawn.sync("openclaw", ["chat", "--message", OPENCLAW_ONBOARDING_PROMPT], {
+        stdio: "inherit",
+    });
+    if (result.error) {
+        throw new Error("Could not launch OpenClaw", { cause: result.error });
+    }
+    if (result.signal === "SIGINT" || result.signal === "SIGTERM")
+        return false;
+    if (result.status !== 0) {
+        throw new Error(`OpenClaw walkthrough exited with status ${result.status ?? "unknown"}`);
+    }
+    return true;
+}

package/dist/lib/connect-runtime.d.ts

@@ -0,0 +1,53 @@
+export declare const NON_INTERACTIVE_TIMEOUT_MS = 10000;
+export type AgentClient = "claude-code" | "codex" | "cursor" | "hermes" | "openclaw" | "opencode";
+type ConnectStage = "started" | "checkpoint" | "completed" | "failed" | "aborted" | "post_install_failed";
+type ConnectFailureStage = "prerequisite_check" | "registration_cleanup" | "registration" | "registration_or_authentication" | "client_oauth" | "cli_install" | "skill_install" | "authentication" | "walkthrough_launch";
+type ConnectFailureReason = "harness_not_installed" | "harness_command_unsupported" | "harness_too_old";
+type ConnectCheckpoint = "prerequisite_ok" | "registered" | "oauth_done" | "cli_installed" | "skill_installed" | "authenticated";
+/** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
+export declare class ConnectInterruptedError extends Error {
+}
+export declare function throwIfInterrupted(result: {
+    signal?: string | null;
+    error?: Error;
+}): void;
+export declare function commandNotFound(error: unknown): boolean;
+export interface ConnectRunState {
+    stage: ConnectFailureStage;
+    settled: boolean;
+}
+interface ConnectStageDetail {
+    failedStage?: ConnectFailureStage;
+    phase?: ConnectCheckpoint;
+    failureReason?: ConnectFailureReason;
+    harnessVersion?: string;
+}
+export interface ConnectTelemetry {
+    attemptId: string;
+    track(stage: ConnectStage, detail?: ConnectStageDetail): void;
+    flush(): Promise<void>;
+}
+/** Terminal events exactly once, whichever of flow or signal handler wins. */
+export declare function settle(state: ConnectRunState, telemetry: ConnectTelemetry, stage: ConnectStage, detail?: ConnectStageDetail): void;
+/** Shared terminal handling: interrupted → aborted, else failed. */
+export declare function runGuarded(state: ConnectRunState, telemetry: ConnectTelemetry, body: () => void | Promise<void>): Promise<void>;
+export interface SupportedCommand {
+    command: string;
+    displayName: string;
+    supportCheck: {
+        args: string[];
+        /** Missing → nothing can work; setup fails. */
+        patterns: RegExp[];
+        /** Missing → degrade to key or deferred auth, never refuse. */
+        optionalPatterns?: RegExp[];
+        unavailableMessage: string;
+    };
+}
+export declare function requireCommandSupport(client: SupportedCommand): {
+    optionalSupported: boolean;
+};
+export declare function createConnectTelemetry(mcpUrl: string, client: AgentClient, opts?: {
+    apiKey?: string;
+    attemptId?: string;
+}): ConnectTelemetry;
+export {};

package/dist/lib/connect-runtime.js

@@ -0,0 +1,186 @@
+import { randomUUID } from "node:crypto";
+import spawn from "cross-spawn";
+import { CONNECT_ATTEMPT_ENV, isAttemptId, resolvedApiKey, takePendingConnectAttempt, } from "./auth.js";
+import { CLI_VERSION } from "./constants.js";
+import { detectHumanInitiated } from "./harness.js";
+import { errLine, sanitizeLine } from "./output.js";
+import { postConnectEvent, telemetryDisabled } from "./setup-telemetry.js";
+import { installSignalGuard } from "./signals.js";
+export const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
+/** 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;
+    }
+}
+export 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.
+    if (result.error?.code === "ETIMEDOUT")
+        return;
+    if (result.signal === "SIGINT" || result.signal === "SIGTERM") {
+        throw new ConnectInterruptedError("Setup interrupted");
+    }
+}
+export function commandNotFound(error) {
+    return error?.code === "ENOENT";
+}
+/** Terminal events exactly once, whichever of flow or signal handler wins. */
+export function settle(state, telemetry, stage, detail) {
+    if (state.settled)
+        return;
+    state.settled = true;
+    telemetry.track(stage, detail);
+}
+// Raw-mode children still surface via throwIfInterrupted; cooked-mode stages
+// (npm/npx/OAuth waits) land here.
+function installConnectSignalGuard(state, telemetry) {
+    return installSignalGuard(async () => {
+        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, else failed. */
+export async function runGuarded(state, telemetry, body) {
+    const uninstallSignalGuard = installConnectSignalGuard(state, telemetry);
+    try {
+        await body();
+    }
+    catch (error) {
+        if (error instanceof ConnectInterruptedError) {
+            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,
+            ...(error instanceof PrerequisiteError
+                ? { failureReason: error.failureReason, harnessVersion: error.harnessVersion }
+                : {}),
+        });
+        throw error;
+    }
+    finally {
+        uninstallSignalGuard();
+        await telemetry.flush();
+    }
+}
+export function requireCommandSupport(client) {
+    const result = spawn.sync(client.command, client.supportCheck.args, {
+        encoding: "utf8",
+        // Agent harnesses export FORCE_COLOR, which makes clients colourise even a piped --help.
+        env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
+        timeout: NON_INTERACTIVE_TIMEOUT_MS,
+    });
+    if (commandNotFound(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 PrerequisiteError(client.supportCheck.unavailableMessage, "harness_command_unsupported", { cause: result.error });
+    }
+    // Belt and braces with the colour env: a client that ignores NO_COLOR still has to match.
+    const output = sanitizeLine(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
+    const listed = (patterns) => patterns.every((pattern) => pattern.test(output));
+    const essential = listed(client.supportCheck.patterns);
+    const optionalSupported = listed(client.supportCheck.optionalPatterns ?? []);
+    if ((!essential || !optionalSupported) && process.env["TINYFISH_DEBUG"]) {
+        errLine(`${client.command} ${client.supportCheck.args.join(" ")} printed:\n${output.trim()}`);
+    }
+    if (!essential) {
+        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_too_old", {
+            harnessVersion: probeHarnessVersion(client.command),
+        });
+    }
+    return { optionalSupported };
+}
+/** 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;
+}
+/**
+ * One page-minted id seeds one install attempt, so `tinyfish onboard` connecting three agents
+ * does not report three installs under it. Later connects in the run fall back to a random id.
+ */
+function takeSeedAttemptId() {
+    const fromEnv = process.env[CONNECT_ATTEMPT_ENV];
+    // Both sources are read-and-clear, and the delete lands before any subprocess inherits it.
+    delete process.env[CONNECT_ATTEMPT_ENV];
+    const parked = takePendingConnectAttempt();
+    return fromEnv && isAttemptId(fromEnv) ? fromEnv : parked;
+}
+export function createConnectTelemetry(mcpUrl, client, opts) {
+    // Consumed even when --url already supplied an id: leaving it behind would let a stale
+    // seed reach the agent this connect launches, or the next connect on this machine.
+    const seeded = takeSeedAttemptId();
+    // A setup-page id (via --url, the env var, or one parked by login) joins "copied the
+    // command" to this install attempt.
+    const attemptId = opts?.attemptId ?? seeded ?? randomUUID();
+    const endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
+    const pending = [];
+    async function deliver(body) {
+        // Ahead of the key read; postConnectEvent's own opt-out check is too late to skip it.
+        if (telemetryDisabled())
+            return;
+        // Resolved per event: `tinyfish auth login` writes the config from a subprocess mid-connect.
+        await postConnectEvent({
+            endpoint,
+            body,
+            attempts: 2,
+            apiKey: resolvedApiKey(opts?.apiKey),
+            label: "connect",
+        });
+    }
+    return {
+        attemptId,
+        // Fire-and-forget; awaiting each event stalls setup when telemetry down.
+        track(stage, detail) {
+            // Absorbed here, not in flush: flush runs in runGuarded's finally, so a rejection would
+            // replace the error the flow is already reporting.
+            pending.push(deliver(JSON.stringify({
+                attempt_id: attemptId,
+                client,
+                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,
+                // Same signal the usage events carry, so TTY and headless connects can be split.
+                is_human_initiated: detectHumanInitiated(),
+            })).catch((error) => {
+                // postConnectEvent is total, so this only fires if something inside deliver starts
+                // throwing. Same channel postConnectEvent uses for its own failures.
+                if (!process.env["TINYFISH_DEBUG"])
+                    return;
+                errLine(`connect telemetry failed: ${error instanceof Error ? error.message : String(error)}`);
+            }));
+        },
+        // Awaited in finally so in-flight events land before exit.
+        async flush() {
+            await Promise.all(pending);
+        },
+    };
+}

package/package.json

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