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

package/dist/commands/connect.d.ts

@@ -2,8 +2,6 @@ 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;

package/dist/commands/connect.js

@@ -1,52 +1,18 @@
 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 { 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 { 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.";
@@ -54,174 +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.";
-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], {
@@ -407,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/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/package.json

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