@tiny-fish/cli 0.19.1-next.177 → 0.19.1-next.179

package/dist/commands/connect.d.ts

@@ -1,25 +1,12 @@
 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;
 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.
- *
- * Reinstalling beats `skills update`: it reports failure through the exit code instead of
- * only in prose, it repairs a copy whose lock entry lost its hash, and it cannot spread the
- * skill to agents the user never connected (`update` re-adds with no --agent, which targets
- * every agent on the machine).
- */
-export declare function updateWebSkill(): 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>;

package/dist/commands/connect.js

@@ -1,394 +1,16 @@
-import * as path from "node:path";
 import spawn from "cross-spawn";
-import { CONNECT_SOURCE, loadConfig, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, validatedApiKey, writeConfig, } from "../lib/auth.js";
+import { CONNECT_SOURCE, saveConnectContext, validateKeyFormat, validatedApiKey, } from "../lib/auth.js";
+import { CLAUDE_CODE, CODEX, HERMES, OPENCLAW, OPENCLAW_SKILL_INSTALL_ARGS, OPENCODE, launchNativeMcpClient, launchOpenClawWalkthrough, openExternalUrl, } from "../lib/connect-clients.js";
+import { ensureCliAuthenticated, installTinyFishCli, installWebSkill, SKILL_INSTALL_TIMEOUT_MS, TINYFISH_CLI_NOT_FOUND_MESSAGE, UPGRADE_HINT, } from "../lib/connect-install.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 { verifyMcpAuth } from "../lib/verify.js";
 export const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
-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.";
-// Supports Hermes without node:util.styleText, so the installer still runs on Node 20.11.
-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.";
-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,
-    },
-};
-export function installTinyFishCli() {
-    errLine("Installing the TinyFish CLI...");
-    const result = spawn.sync("npm", ["install", "--global", TINYFISH_CLI_INSTALL_SPEC], {
-        stdio: "inherit",
-        timeout: SKILL_INSTALL_TIMEOUT_MS,
-    });
-    if (result.error || result.status !== 0) {
-        throwIfInterrupted(result);
-        throw new Error("Could not install the TinyFish CLI", { cause: result.error });
-    }
-}
-/** `skills add` is an unconditional overwrite, so it doubles as the refresh path. */
-function skillAddArgs(skillAgents) {
-    return [
-        "-y",
-        SKILLS_CLI_PACKAGE,
-        "add",
-        TINYFISH_WEB_SKILL_SOURCE,
-        "--skill",
-        TINYFISH_WEB_SKILL,
-        "--global",
-        "--agent",
-        ...skillAgents,
-        "--yes",
-    ];
-}
-// npx resolves from PATH, which a global npm install may not have exported yet.
-function skillSpawnEnv() {
-    return {
-        ...process.env,
-        PATH: `${path.dirname(process.execPath)}${path.delimiter}${process.env.PATH ?? ""}`,
-    };
-}
-function installWebSkill(client) {
-    errLine(`Installing the TinyFish web skill in ${client.displayName}...`);
-    const result = spawn.sync("npx", skillAddArgs([client.skillAgent]), {
-        env: skillSpawnEnv(),
-        stdio: "inherit",
-        timeout: SKILL_INSTALL_TIMEOUT_MS,
-    });
-    if (result.error || result.status !== 0) {
-        throwIfInterrupted(result);
-        throw new Error(`Could not install the TinyFish web skill in ${client.displayName}`, {
-            cause: result.error,
-        });
-    }
-}
-// The `skills` update flow exits 0 even when it fails, so status alone proves nothing.
-// Safe to match on because SKILLS_CLI_PACKAGE is pinned.
-const SKILL_UPDATE_FAILURE_PATTERN = /Failed to (?:update|check|fetch)/;
-const SKILL_NOT_INSTALLED_PATTERN = /No installed skills found matching/;
-// A lock entry with no recorded hash is untrackable, so `skills` reports it as skipped rather
-// than failed. Left undetected that reads as "up to date" while nothing was refreshed.
-const SKILL_UNCHECKABLE_PATTERN = /cannot be checked automatically/;
-// `skills add` exits non-zero on a fatal error, but per-skill install failures only print.
-const SKILL_INSTALL_FAILURE_PATTERN = /Failed to install/;
-/**
- * Refresh the skill we installed, for the harnesses we installed it in.
- *
- * Reinstalling beats `skills update`: it reports failure through the exit code instead of
- * only in prose, it repairs a copy whose lock entry lost its hash, and it cannot spread the
- * skill to agents the user never connected (`update` re-adds with no --agent, which targets
- * every agent on the machine).
- */
-export function updateWebSkill() {
-    // One entry per `tinyfish connect <client>`, persisted by PF-3169.
-    const connected = loadConfig().connect ?? {};
-    const skillAgents = [CLAUDE_CODE, CODEX, HERMES, OPENCODE]
-        .filter((client) => connected[client.connectClient])
-        .map((client) => client.skillAgent);
-    const hasOpenClaw = Boolean(connected["openclaw"]);
-    // Installs predating PF-3169 recorded nothing; ask `skills` to refresh what it tracks.
-    if (skillAgents.length === 0 && !hasOpenClaw) {
-        refreshWebSkillByHash();
-        return;
-    }
-    if (skillAgents.length > 0)
-        reinstallWebSkill(skillAgents);
-    // OpenClaw keeps its skill under its own CLI, so it needs its own refresh.
-    if (hasOpenClaw)
-        reinstallOpenClawSkill();
-}
-function reinstallOpenClawSkill() {
-    errLine("Refreshing the TinyFish skill in OpenClaw...");
-    const result = spawn.sync("openclaw", OPENCLAW_SKILL_INSTALL_ARGS, { stdio: "inherit" });
-    // OpenClaw may have been removed since connect; a stale context entry must not fail an
-    // upgrade that otherwise succeeded.
-    if (commandNotFound(result.error)) {
-        errLine("OpenClaw is not on PATH, so its TinyFish skill was left unchanged.");
-        return;
-    }
-    if (result.error || result.status !== 0) {
-        throwIfInterrupted(result);
-        throw new Error("Could not refresh the TinyFish skill in OpenClaw", { cause: result.error });
-    }
-}
-function reinstallWebSkill(skillAgents) {
-    errLine(`Refreshing the TinyFish web skill for ${skillAgents.join(", ")}...`);
-    const result = spawn.sync("npx", skillAddArgs(skillAgents), {
-        encoding: "utf8",
-        env: skillSpawnEnv(),
-        timeout: SKILL_INSTALL_TIMEOUT_MS,
-    });
-    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-    if (output.trim())
-        errLine(output.trimEnd());
-    if (result.error || result.status !== 0 || SKILL_INSTALL_FAILURE_PATTERN.test(output)) {
-        throwIfInterrupted(result);
-        throw new Error("Could not refresh the TinyFish web skill", { cause: result.error });
-    }
-}
-/** Fallback when no harness is recorded: ask `skills` to refresh whatever it tracks. */
-function refreshWebSkillByHash() {
-    errLine("Refreshing the TinyFish web skill...");
-    const result = spawn.sync("npx", ["-y", SKILLS_CLI_PACKAGE, "update", TINYFISH_WEB_SKILL, "--global", "--yes"], {
-        encoding: "utf8",
-        env: skillSpawnEnv(),
-        timeout: SKILL_INSTALL_TIMEOUT_MS,
-    });
-    // Piped rather than inherited so the output can be inspected; echoed back for the user.
-    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-    if (output.trim())
-        errLine(output.trimEnd());
-    if (result.error || result.status !== 0 || SKILL_UPDATE_FAILURE_PATTERN.test(output)) {
-        throwIfInterrupted(result);
-        throw new Error("Could not refresh the TinyFish web skill", { cause: result.error });
-    }
-    if (SKILL_UNCHECKABLE_PATTERN.test(output)) {
-        errLine("Run `tinyfish connect <client>` to reinstall the skill and restore update tracking.");
-        throw new Error("The TinyFish web skill cannot be checked for updates");
-    }
-    if (SKILL_NOT_INSTALLED_PATTERN.test(output)) {
-        errLine("No use-tinyfish skill installed. Run `tinyfish connect <client>` to add it.");
-    }
-}
-function ensureCliAuthenticated(source, apiKey) {
-    const envKey = apiKey ?? process.env["TINYFISH_API_KEY"];
-    if (envKey) {
-        if (!validateKeyFormat(envKey)) {
-            throw new Error("TINYFISH_API_KEY has invalid format");
-        }
-        // Throwing variant: a write failure must reach connect's catch/flush, not exit(1) past it.
-        writeConfig(envKey);
-        persistApiKeyToEnvironment(envKey);
-        return;
-    }
-    const authStatus = spawn.sync("tinyfish", ["auth", "status"], {
-        stdio: "ignore",
-        timeout: NON_INTERACTIVE_TIMEOUT_MS,
-    });
-    if (commandNotFound(authStatus.error)) {
-        throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: authStatus.error });
-    }
-    if (authStatus.status === 0)
-        return;
-    errLine("Signing in to the TinyFish CLI...");
-    const loginResult = spawn.sync("tinyfish", ["auth", "login", "--source", source], {
-        stdio: "inherit",
-    });
-    if (commandNotFound(loginResult.error)) {
-        throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: loginResult.error });
-    }
-    if (loginResult.error || loginResult.status !== 0) {
-        throwIfInterrupted(loginResult);
-        throw new Error("Could not authenticate the TinyFish CLI", { cause: loginResult.error });
-    }
-}
 function removeExistingRegistration(client, removal) {
     const result = spawn.sync(client.command, removal.args, {
         encoding: "utf8",
@@ -407,38 +29,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 };
@@ -587,6 +177,7 @@ export async function connectOpenClaw(options) {
         errLine("Installing the TinyFish skill in OpenClaw...");
         const skillInstallResult = spawn.sync("openclaw", OPENCLAW_SKILL_INSTALL_ARGS, {
             stdio: "inherit",
+            timeout: SKILL_INSTALL_TIMEOUT_MS,
         });
         if (skillInstallResult.error || skillInstallResult.status !== 0) {
             throwIfInterrupted(skillInstallResult);
@@ -693,13 +284,7 @@ export async function connectCursor(options) {
 }
 /** Best-effort: false when no handler/open fails — caller falls back to reload copy. */
 function launchCursorDeeplink(mcpUrl) {
-    const deepLink = cursorInstallDeeplink(mcpUrl);
-    const [command, args] = process.platform === "darwin"
-        ? ["open", [deepLink]]
-        : process.platform === "win32"
-            ? ["cmd", ["/c", "start", "", deepLink]]
-            : ["xdg-open", [deepLink]];
-    const result = spawn.sync(command, args, { stdio: "ignore" });
+    const result = openExternalUrl(cursorInstallDeeplink(mcpUrl));
     return !result.error && result.status === 0;
 }
 export function launchAgent(client) {

package/dist/commands/upgrade.js

@@ -5,8 +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 { installTinyFishCli, updateWebSkill } from "../lib/connect-install.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,40 @@
+import spawn from "cross-spawn";
+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;
+/**
+ * `cmd` re-parses its command line after `/c`, so an unquoted `&` in the query string ends the
+ * command and truncates the URL. Quoting needs windowsVerbatimArguments, or Node escapes the
+ * quotes back out. Untested on Windows.
+ */
+export declare function openExternalUrl(url: string): ReturnType<typeof spawn.sync>;
+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,249 @@
+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],
+};
+/**
+ * `cmd` re-parses its command line after `/c`, so an unquoted `&` in the query string ends the
+ * command and truncates the URL. Quoting needs windowsVerbatimArguments, or Node escapes the
+ * quotes back out. Untested on Windows.
+ */
+export function openExternalUrl(url) {
+    if (process.platform === "darwin")
+        return spawn.sync("open", [url], { stdio: "ignore" });
+    if (process.platform === "win32") {
+        return spawn.sync("cmd", ["/c", "start", '""', `"${url}"`], {
+            stdio: "ignore",
+            windowsVerbatimArguments: true,
+        });
+    }
+    return spawn.sync("xdg-open", [url], { stdio: "ignore" });
+}
+function launchCodexWalkthrough() {
+    const deepLink = new URL("codex://new");
+    deepLink.searchParams.set("prompt", DEFAULT_ONBOARDING_PROMPT);
+    deepLink.searchParams.set("path", process.cwd());
+    const result = openExternalUrl(deepLink.toString());
+    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-install.d.ts

@@ -0,0 +1,17 @@
+import { type NativeMcpClient } from "./connect-clients.js";
+import { type AgentClient } from "./connect-runtime.js";
+export declare const SKILL_INSTALL_TIMEOUT_MS = 120000;
+export declare const TINYFISH_CLI_NOT_FOUND_MESSAGE = "TinyFish CLI installed but is not available on PATH. Open a new terminal and retry.";
+export declare const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI and skill.";
+export declare function installTinyFishCli(): void;
+export declare function installWebSkill(client: NativeMcpClient): void;
+/**
+ * Refresh the skill we installed, for the harnesses we installed it in.
+ *
+ * Reinstalling beats `skills update`: it reports failure through the exit code instead of
+ * only in prose, it repairs a copy whose lock entry lost its hash, and it cannot spread the
+ * skill to agents the user never connected (`update` re-adds with no --agent, which targets
+ * every agent on the machine).
+ */
+export declare function updateWebSkill(): void;
+export declare function ensureCliAuthenticated(source: AgentClient, apiKey?: string): void;

package/dist/lib/connect-install.js

@@ -0,0 +1,196 @@
+import * as path from "node:path";
+import spawn from "cross-spawn";
+import { loadConfig, persistApiKeyToEnvironment, validateKeyFormat, writeConfig } from "./auth.js";
+import { CLAUDE_CODE, CODEX, HERMES, OPENCLAW_SKILL_INSTALL_ARGS, OPENCODE, } from "./connect-clients.js";
+import { commandNotFound, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "./connect-runtime.js";
+import { TINYFISH_CLI_PACKAGE } from "./constants.js";
+import { errLine } from "./output.js";
+export const SKILL_INSTALL_TIMEOUT_MS = 120_000;
+export 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.";
+// Supports Hermes without node:util.styleText, so the installer still runs on Node 20.11.
+const SKILLS_CLI_PACKAGE = "skills@1.5.15";
+const TINYFISH_WEB_SKILL_SOURCE = "tinyfish-io/tinyfish-cookbook";
+const TINYFISH_WEB_SKILL = "use-tinyfish";
+export function installTinyFishCli() {
+    errLine("Installing the TinyFish CLI...");
+    const result = spawn.sync("npm", ["install", "--global", TINYFISH_CLI_INSTALL_SPEC], {
+        stdio: "inherit",
+        timeout: SKILL_INSTALL_TIMEOUT_MS,
+    });
+    if (result.error || result.status !== 0) {
+        throwIfInterrupted(result);
+        throw new Error("Could not install the TinyFish CLI", { cause: result.error });
+    }
+}
+/** `skills add` is an unconditional overwrite, so it doubles as the refresh path. */
+function skillAddArgs(skillAgents) {
+    return [
+        "-y",
+        SKILLS_CLI_PACKAGE,
+        "add",
+        TINYFISH_WEB_SKILL_SOURCE,
+        "--skill",
+        TINYFISH_WEB_SKILL,
+        "--global",
+        "--agent",
+        ...skillAgents,
+        "--yes",
+    ];
+}
+// npx resolves from PATH, which a global npm install may not have exported yet.
+function skillSpawnEnv() {
+    return {
+        ...process.env,
+        PATH: `${path.dirname(process.execPath)}${path.delimiter}${process.env.PATH ?? ""}`,
+    };
+}
+// The `skills` update flow exits 0 even when it fails, so status alone proves nothing.
+// Safe to match on because SKILLS_CLI_PACKAGE is pinned.
+const SKILL_UPDATE_FAILURE_PATTERN = /Failed to (?:update|check|fetch)/;
+const SKILL_NOT_INSTALLED_PATTERN = /No installed skills found matching/;
+// A lock entry with no recorded hash is untrackable, so `skills` reports it as skipped rather
+// than failed. Left undetected that reads as "up to date" while nothing was refreshed.
+const SKILL_UNCHECKABLE_PATTERN = /cannot be checked automatically/;
+// `skills add` exits non-zero on a fatal error, but per-skill install failures only print.
+const SKILL_INSTALL_FAILURE_PATTERN = /Failed to install/;
+export function installWebSkill(client) {
+    errLine(`Installing the TinyFish web skill in ${client.displayName}...`);
+    // Piped rather than inherited so the per-skill failure line can be matched; echoed back
+    // so the user still sees what `skills` reported.
+    const result = spawn.sync("npx", skillAddArgs([client.skillAgent]), {
+        encoding: "utf8",
+        env: skillSpawnEnv(),
+        timeout: SKILL_INSTALL_TIMEOUT_MS,
+    });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    if (output.trim())
+        errLine(output.trimEnd());
+    if (result.error || result.status !== 0 || SKILL_INSTALL_FAILURE_PATTERN.test(output)) {
+        throwIfInterrupted(result);
+        throw new Error(`Could not install the TinyFish web skill in ${client.displayName}`, {
+            cause: result.error,
+        });
+    }
+}
+/**
+ * Refresh the skill we installed, for the harnesses we installed it in.
+ *
+ * Reinstalling beats `skills update`: it reports failure through the exit code instead of
+ * only in prose, it repairs a copy whose lock entry lost its hash, and it cannot spread the
+ * skill to agents the user never connected (`update` re-adds with no --agent, which targets
+ * every agent on the machine).
+ */
+export function updateWebSkill() {
+    // One entry per `tinyfish connect <client>`, persisted by PF-3169.
+    const connected = loadConfig().connect ?? {};
+    const skillAgents = [CLAUDE_CODE, CODEX, HERMES, OPENCODE]
+        .filter((client) => connected[client.connectClient])
+        .map((client) => client.skillAgent);
+    const hasOpenClaw = Boolean(connected["openclaw"]);
+    // Installs predating PF-3169 recorded nothing; ask `skills` to refresh what it tracks.
+    if (skillAgents.length === 0 && !hasOpenClaw) {
+        refreshWebSkillByHash();
+        return;
+    }
+    if (skillAgents.length > 0)
+        reinstallWebSkill(skillAgents);
+    // OpenClaw keeps its skill under its own CLI, so it needs its own refresh.
+    if (hasOpenClaw)
+        reinstallOpenClawSkill();
+}
+function reinstallOpenClawSkill() {
+    errLine("Refreshing the TinyFish skill in OpenClaw...");
+    const result = spawn.sync("openclaw", OPENCLAW_SKILL_INSTALL_ARGS, {
+        stdio: "inherit",
+        timeout: SKILL_INSTALL_TIMEOUT_MS,
+    });
+    // OpenClaw may have been removed since connect; a stale context entry must not fail an
+    // upgrade that otherwise succeeded.
+    if (commandNotFound(result.error)) {
+        errLine("OpenClaw is not on PATH, so its TinyFish skill was left unchanged.");
+        return;
+    }
+    if (result.error || result.status !== 0) {
+        throwIfInterrupted(result);
+        throw new Error("Could not refresh the TinyFish skill in OpenClaw", { cause: result.error });
+    }
+}
+function reinstallWebSkill(skillAgents) {
+    errLine(`Refreshing the TinyFish web skill for ${skillAgents.join(", ")}...`);
+    const result = spawn.sync("npx", skillAddArgs(skillAgents), {
+        encoding: "utf8",
+        env: skillSpawnEnv(),
+        timeout: SKILL_INSTALL_TIMEOUT_MS,
+    });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    if (output.trim())
+        errLine(output.trimEnd());
+    if (result.error || result.status !== 0 || SKILL_INSTALL_FAILURE_PATTERN.test(output)) {
+        throwIfInterrupted(result);
+        throw new Error("Could not refresh the TinyFish web skill", { cause: result.error });
+    }
+}
+/** Fallback when no harness is recorded: ask `skills` to refresh whatever it tracks. */
+function refreshWebSkillByHash() {
+    errLine("Refreshing the TinyFish web skill...");
+    const result = spawn.sync("npx", ["-y", SKILLS_CLI_PACKAGE, "update", TINYFISH_WEB_SKILL, "--global", "--yes"], {
+        encoding: "utf8",
+        env: skillSpawnEnv(),
+        timeout: SKILL_INSTALL_TIMEOUT_MS,
+    });
+    // Piped rather than inherited so the output can be inspected; echoed back for the user.
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    if (output.trim())
+        errLine(output.trimEnd());
+    if (result.error || result.status !== 0 || SKILL_UPDATE_FAILURE_PATTERN.test(output)) {
+        throwIfInterrupted(result);
+        throw new Error("Could not refresh the TinyFish web skill", { cause: result.error });
+    }
+    if (SKILL_UNCHECKABLE_PATTERN.test(output)) {
+        errLine("Run `tinyfish connect <client>` to reinstall the skill and restore update tracking.");
+        throw new Error("The TinyFish web skill cannot be checked for updates");
+    }
+    if (SKILL_NOT_INSTALLED_PATTERN.test(output)) {
+        errLine("No use-tinyfish skill installed. Run `tinyfish connect <client>` to add it.");
+    }
+}
+export function ensureCliAuthenticated(source, apiKey) {
+    const envKey = apiKey ?? process.env["TINYFISH_API_KEY"];
+    if (envKey) {
+        if (!validateKeyFormat(envKey)) {
+            throw new Error("TINYFISH_API_KEY has invalid format");
+        }
+        // Throwing variant: a write failure must reach connect's catch/flush, not exit(1) past it.
+        writeConfig(envKey);
+        persistApiKeyToEnvironment(envKey);
+        return;
+    }
+    const authStatus = spawn.sync("tinyfish", ["auth", "status"], {
+        stdio: "ignore",
+        timeout: NON_INTERACTIVE_TIMEOUT_MS,
+    });
+    if (commandNotFound(authStatus.error)) {
+        throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: authStatus.error });
+    }
+    if (authStatus.status === 0)
+        return;
+    // A crashed or timed-out probe says nothing about the stored key, so it must not read as
+    // "not signed in" and drop the user into an interactive login they never asked for.
+    throwIfInterrupted(authStatus);
+    if (authStatus.error) {
+        throw new Error("Could not read TinyFish CLI auth status", { cause: authStatus.error });
+    }
+    errLine("Signing in to the TinyFish CLI...");
+    const loginResult = spawn.sync("tinyfish", ["auth", "login", "--source", source], {
+        stdio: "inherit",
+    });
+    if (commandNotFound(loginResult.error)) {
+        throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: loginResult.error });
+    }
+    if (loginResult.error || loginResult.status !== 0) {
+        throwIfInterrupted(loginResult);
+        throw new Error("Could not authenticate the TinyFish CLI", { cause: loginResult.error });
+    }
+}

package/dist/lib/connect-runtime.js

@@ -178,9 +178,10 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
                 errLine(`connect telemetry failed: ${error instanceof Error ? error.message : String(error)}`);
             }));
         },
-        // Awaited in finally so in-flight events land before exit.
+        // Awaited in finally so in-flight events land before exit. Drains, so the signal-guard
+        // flush and the finally flush do not re-await the same events.
         async flush() {
-            await Promise.all(pending);
+            await Promise.all(pending.splice(0));
         },
     };
 }

package/package.json

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