@tiny-fish/cli 0.35.0 → 0.35.1-next.290

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

@@ -1,6 +1,7 @@
 import spawn from 'cross-spawn';
 import { type Harness } from './harness-detect.js';
 import { type AgentClient, type SupportedCommand } from './connect-runtime.js';
+import { type HarnessSpec, type SkillAgent } from './harness-spec.js';
 export declare const OPENCLAW_SKILL_INSTALL_ARGS: readonly string[];
 /** `openclaw skills` has no uninstall; ClawHub removes from the global dir. */
 export declare function openclawSkillUninstall(): {
@@ -11,12 +12,11 @@ export declare function openclawSkillUninstall(): {
 };
 export declare const DEFAULT_ONBOARDING_PROMPT: string;
 export declare const OPENCLAW_ONBOARDING_PROMPT: string;
-/** The `skills` CLI's own agent names — not ours, and not every harness has one. */
-export type SkillAgent = 'claude-code' | 'codex' | 'cursor' | 'hermes-agent' | 'opencode';
+export type { SkillAgent };
 /** Cursor writes its own MCP config, so it has no descriptor to carry this. */
 export declare const CURSOR_SKILL_TARGET: {
     readonly skillAgent: "cursor";
-    readonly displayName: "Cursor";
+    readonly displayName: string;
 };
 /** The harness reads the key from its own store. */
 export interface SeededInstall {
@@ -35,12 +35,8 @@ export interface SeededInstall {
         tag?: string;
     };
 }
-interface BaseMcpClient extends SupportedCommand {
+interface BaseMcpClient extends SupportedCommand, Pick<HarnessSpec, 'skillAgent' | 'nonInteractiveAdd' | 'signInHint' | 'degradedAuthNotes' | 'postConnectNote'> {
     connectClient: Exclude<AgentClient, 'openclaw'>;
-    /** Omitted where the `skills` CLI has no agent for this harness (Grok ships its own plugin). */
-    skillAgent?: SkillAgent;
-    /** Capturable: this `mcp add` never runs OAuth inline; unset stays inherited. */
-    nonInteractiveAdd?: true;
     /** Replaces `addArgs` when a stored key is available: key auth removes the OAuth hop. */
     keyAuth?: {
         /** Which variable the client reads the key from. */
@@ -49,16 +45,9 @@ interface BaseMcpClient extends SupportedCommand {
         /** Writes into the harness's store, so connect verifies the key first. */
         seedKey?: (apiKey: string) => SeededInstall;
     };
-    /** Shown when a keyless install leaves sign-in to the harness. */
-    signInHint?: string;
     loginArgs?: string[];
     /** Keyless `mcp add` itself blocks on the browser OAuth. */
     oauthInAdd?: boolean;
-    /** Replaces the `loginArgs` step when `supportCheck.optionalPatterns` miss. */
-    degradedAuthNotes?: {
-        keyed: string;
-        deferred: string;
-    };
     removals: {
         args: string[];
         label: string;
@@ -67,8 +56,6 @@ interface BaseMcpClient extends SupportedCommand {
     launchWalkthrough?: () => void;
     /** Own window, never inherits stdio; reports its own outcome. */
     detachedLaunch?: () => WalkthroughOutcome;
-    /** Printed after a successful connect, on both the launch and non-launch paths. */
-    postConnectNote?: string;
     /** Post-install like the skill step: failures warn, never fail the attempt. */
     extraPostInstall?: (options: {
         apiKey?: string;
@@ -95,42 +82,29 @@ export interface KeyRequiredMcpClient extends BaseMcpClient {
     loginArgs?: never;
 }
 export type NativeMcpClient = OauthCapableMcpClient | KeyRequiredMcpClient;
-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 GROK: NativeMcpClient;
 /** `mcp add` exits 0 after saving nothing, or a disabled entry. */
 export declare function hermesRegistrationEnabled(home: string): {
     ok: boolean;
     detail?: string;
     tag?: string;
 };
-export declare const HERMES: KeyRequiredMcpClient;
-export declare const OPENCODE: NativeMcpClient;
-/** Every native MCP client. Derive from this, so a new harness cannot be missed. */
 export declare const NATIVE_MCP_CLIENTS: readonly NativeMcpClient[];
 /** Native descriptor by harness id; Cursor and OpenClaw have none. */
 export declare const NATIVE_BY_HARNESS: Map<"openclaw" | "grok" | "cursor" | "codex" | "hermes" | "opencode" | "claude-code", NativeMcpClient>;
+export declare const CLAUDE_CODE: NativeMcpClient;
+export declare const CODEX: NativeMcpClient;
+export declare const GROK: NativeMcpClient;
+export declare const HERMES: NativeMcpClient;
+export declare const OPENCODE: NativeMcpClient;
 export declare const OPENCLAW: SupportedCommand;
 /** Traits with no native descriptor to live on (Cursor and OpenClaw included). */
-export interface HarnessCapabilities {
-    /** Sign-in is the CLI's own interactive `tinyfish auth login`. */
-    signInViaCliLogin: boolean;
-    /** Stored-key auth verification works against this harness's config. */
-    canVerifyAuth: boolean;
-    /** The CLI holds or writes the key; no harness `mcp add` carries it. */
-    keyHeldByCli: boolean;
-    /** Connect writes the MCP config file; no harness binary is spawned. */
-    cliWritesConfig: boolean;
-    /** `mcp add` succeeds unauthenticated; OAuth lands at first tool use. */
-    authDeferredAtInstall: boolean;
-}
-/** Required booleans: a new harness or new flag fails to compile undecided. */
+export type HarnessCapabilities = Pick<HarnessSpec, 'signInViaCliLogin' | 'canVerifyAuth' | 'keyHeldByCli' | 'cliWritesConfig' | 'authDeferredAtInstall'>;
 export declare const HARNESS_CAPABILITIES: Record<Harness, HarnessCapabilities>;
 /** "printed" = handed to the user to paste; the walkthrough was never started for them. */
 export type WalkthroughOutcome = 'launched' | 'printed';
@@ -138,4 +112,3 @@ export type WalkthroughOutcome = 'launched' | 'printed';
 type OnWalkthroughDecided = (outcome: WalkthroughOutcome) => void | Promise<void>;
 export declare function launchNativeMcpClient(client: NativeMcpClient, onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;
 export declare function launchOpenClawWalkthrough(onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;
-export {};

package/dist/lib/connect-clients.js

@@ -5,57 +5,11 @@ import { harnessConfigPath } from './harness-detect.js';
 import { errLine, sanitizeLine, warnLine } from './output.js';
 import { ConnectStepError, spawnStepError, } from './connect-runtime.js';
 import { TINYFISH_API_KEY_VAR } from './constants.js';
+import { ALL_HARNESSES, HARNESS_SPECS, NATIVE_HARNESSES, harnessSpec, } from './harness-spec.js';
 import { HERMES_KEY_VAR, captureHermesKeyRestore, hermesEnvPath, resolveHermesHome, writeHermesKey, } from './hermes-env.js';
 import { hermesConfigPath, readHermesEntry } from './hermes-config.js';
-import { HERMES_PLUGIN_NAME, installHermesPlugin, setHermesWebBackends } from './hermes-plugin.js';
+import { installHermesPlugin, setHermesWebBackends } from './hermes-plugin.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. Already have a TinyFish API key? ' +
-    'Run `tinyfish connect claude-code --api-key <key>` instead.';
-const CODEX_MCP_URL_UNAVAILABLE_MESSAGE = 'Could not confirm this Codex installation supports remote MCP servers: `codex mcp add ' +
-    '--help` did not list `--url`. Update Codex and retry, or add TinyFish manually with ' +
-    '`codex mcp add`.' +
-    SUPPORT_CHECK_DEBUG_HINT;
-const CODEX_KEYED_FALLBACK_NOTE = 'Using your stored TinyFish API key: this Codex cannot report whether an OAuth sign-in ' +
-    'finished, so no browser sign-in is attempted.';
-const CODEX_DEFERRED_AUTH_NOTE = 'TinyFish is registered in Codex but not signed in: this Codex predates reliable sign-in ' +
-    'reporting. Run `codex mcp login tinyfish` to sign in, or update Codex with ' +
-    '`npm install -g @openai/codex@latest` for one-command sign-in.';
-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 GROK_HTTP_UNAVAILABLE_MESSAGE = 'Could not confirm this Grok installation supports remote MCP servers: `grok mcp add --help` ' +
-    'did not list `--transport`. Update Grok and retry, or add TinyFish manually with ' +
-    '`grok mcp add`.' +
-    SUPPORT_CHECK_DEBUG_HINT;
-// Grok has no `mcp login`; sign-in only happens inside the TUI. No key nudge here: a revoked
-// key leaves Grok with no OAuth fallback, and doctor cannot spot that yet (PF-3618).
-const GROK_SIGN_IN_HINT = 'TinyFish is registered in Grok. Open Grok, run `/mcps`, select tinyfish, and press `i` to ' +
-    'sign in.';
-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 = [
@@ -95,53 +49,9 @@ export const OPENCLAW_ONBOARDING_PROMPT = 'I just installed the TinyFish skill.
     '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.';
 /** Cursor writes its own MCP config, so it has no descriptor to carry this. */
-export const CURSOR_SKILL_TARGET = { skillAgent: 'cursor', displayName: 'Cursor' };
-const HEADER_FLAG = /(?:^|\s)--header(?:[\s<=]|$)/m;
-const claudeAddArgs = (mcpUrl) => [
-    'mcp',
-    'add',
-    '--scope',
-    'user',
-    '--transport',
-    'http',
-    'tinyfish',
-    mcpUrl,
-];
-const urlAddArgs = (mcpUrl) => ['mcp', 'add', 'tinyfish', '--url', mcpUrl];
-// OpenCode takes `--header NAME=VALUE`, not Claude Code's `NAME: VALUE`.
-const headerKeyAuth = {
-    addArgs: (mcpUrl, apiKey) => [...urlAddArgs(mcpUrl), '--header', `X-API-Key=${apiKey}`],
-};
-export const CLAUDE_CODE = {
-    command: 'claude',
-    connectClient: 'claude-code',
-    skillAgent: 'claude-code',
-    nonInteractiveAdd: true,
-    displayName: 'Claude Code',
-    supportCheck: {
-        args: ['mcp', '--help'],
-        patterns: [/^\s*add(?:\s|\[)/m],
-        optionalPatterns: [/^\s*login(?:\s|\[)/m],
-        keyAuthPattern: HEADER_FLAG,
-        unavailableMessage: MCP_ADD_UNAVAILABLE_MESSAGE,
-    },
-    keyAuth: {
-        addArgs: (mcpUrl, apiKey) => [...claudeAddArgs(mcpUrl), '--header', `X-API-Key: ${apiKey}`],
-    },
-    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) => claudeAddArgs(mcpUrl),
+export const CURSOR_SKILL_TARGET = {
+    skillAgent: HARNESS_SPECS.cursor.skillAgent,
+    displayName: HARNESS_SPECS.cursor.displayName,
 };
 /**
  * `cmd` re-parses its command line after `/c`, so an unquoted `&` in the query string ends the
@@ -172,69 +82,6 @@ function launchCodexWalkthrough() {
     errLine('Codex opened with the TinyFish walkthrough ready. Send the prompt to start.');
     return 'launched';
 }
-export const CODEX = {
-    command: 'codex',
-    connectClient: 'codex',
-    skillAgent: 'codex',
-    displayName: 'Codex',
-    supportCheck: {
-        args: ['mcp', 'add', '--help'],
-        patterns: [/--url(?:[\s<=]|$)/m],
-        // Codex before ~0.142 reports `o_auth` for a server it never signed in to, so the
-        // sign-in probe lies; `--oauth-resource` is the only marker separating the two.
-        optionalPatterns: [/--oauth-resource(?:[\s<=]|$)/m],
-        keyAuthPattern: /(?:^|\s)--bearer-token-env-var(?:[\s<=]|$)/m,
-        unavailableMessage: CODEX_MCP_URL_UNAVAILABLE_MESSAGE,
-    },
-    degradedAuthNotes: {
-        keyed: CODEX_KEYED_FALLBACK_NOTE,
-        deferred: CODEX_DEFERRED_AUTH_NOTE,
-    },
-    // Codex has no `--header`; the MCP server takes a key as `Bearer sk-…`.
-    keyAuth: {
-        envVar: TINYFISH_API_KEY_VAR,
-        addArgs: (mcpUrl) => [...urlAddArgs(mcpUrl), '--bearer-token-env-var', TINYFISH_API_KEY_VAR],
-    },
-    detachedLaunch: launchCodexWalkthrough,
-    loginArgs: ['mcp', 'login', 'tinyfish'],
-    removals: [{ args: ['mcp', 'remove', 'tinyfish'], label: 'TinyFish registration from Codex' }],
-    // `--oauth-resource` duplicates the resource Codex discovers; Clerk rejects both.
-    // `mcp add` still runs OAuth inline, so `loginArgs` stays a retry.
-    addArgs: urlAddArgs,
-};
-const grokAddArgs = (mcpUrl) => [
-    'mcp',
-    'add',
-    '--transport',
-    'http',
-    'tinyfish',
-    mcpUrl,
-];
-export const GROK = {
-    command: 'grok',
-    connectClient: 'grok',
-    nonInteractiveAdd: true,
-    displayName: 'Grok',
-    supportCheck: {
-        args: ['mcp', 'add', '--help'],
-        patterns: [/--transport(?:[\s<=]|$)/m],
-        keyAuthPattern: HEADER_FLAG,
-        unavailableMessage: GROK_HTTP_UNAVAILABLE_MESSAGE,
-    },
-    // X-API-Key is dropped whenever the server advertises OAuth metadata; Bearer is not.
-    // Grok expands `${VAR}` in headers at load, so the key stays out of argv and config.toml.
-    keyAuth: {
-        envVar: TINYFISH_API_KEY_VAR,
-        addArgs: (mcpUrl) => [
-            ...grokAddArgs(mcpUrl),
-            '--header',
-            `Authorization: Bearer \${${TINYFISH_API_KEY_VAR}}`,
-        ],
-    },
-    signInHint: GROK_SIGN_IN_HINT,
-    removals: [{ args: ['mcp', 'remove', 'tinyfish'], label: 'TinyFish registration from Grok' }],
-    addArgs: grokAddArgs,
-};
 // Handover: spawn errors are ours; the exit is the user's.
 function handOverTerminal(command, args, displayName) {
     const result = spawn.sync(command, args, { stdio: 'inherit' });
@@ -313,132 +160,129 @@ function installHermesWebPlugin({ apiKey, verbose }) {
     installHermesPlugin(home, apiKey, { verbose });
     setHermesWebBackends(home);
 }
-export const HERMES = {
-    command: 'hermes',
-    connectClient: 'hermes',
-    skillAgent: 'hermes-agent',
-    displayName: 'Hermes',
-    keyRequired: true,
-    supportCheck: {
-        args: ['mcp', 'add', '--help'],
-        patterns: [/--auth\s+\{[^}]*oauth[^}]*\}/],
-        keyAuthPattern: /--auth\s+\{[^}]*header[^}]*\}/,
-        unavailableMessage: HERMES_OAUTH_UNAVAILABLE_MESSAGE,
-    },
-    // No envVar: key goes into Hermes' .env, not the shell.
-    keyAuth: {
-        addArgs: (mcpUrl) => [...urlAddArgs(mcpUrl), '--auth', 'header'],
-        seedKey: seedHermesKey,
-    },
-    removals: [{ args: ['mcp', 'remove', 'tinyfish'], label: 'TinyFish registration from Hermes' }],
-    extraPostInstall: installHermesWebPlugin,
-    uninstallExtra: {
-        args: ['plugins', 'uninstall', HERMES_PLUGIN_NAME],
-        label: 'TinyFish web plugin from Hermes',
-    },
-    launchWalkthrough: launchHermesWalkthrough,
-    postConnectNote: 'Restart your Hermes session to pick up TinyFish — Hermes discovers MCP servers at startup.',
-};
 // 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() {
     handOverTerminal('opencode', ['--prompt', DEFAULT_ONBOARDING_PROMPT], 'OpenCode');
 }
-export const OPENCODE = {
-    command: 'opencode',
-    connectClient: 'opencode',
-    skillAgent: 'opencode',
-    nonInteractiveAdd: true,
-    displayName: 'OpenCode',
-    supportCheck: {
-        args: ['mcp', 'add', '--help'],
-        patterns: [/--url(?:\s|$)/m],
-        keyAuthPattern: HEADER_FLAG,
-        unavailableMessage: OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE,
+/** "positional": flags before `tinyfish <url>`. "flag": flags after `--url`. */
+function specAddArgs(spec, mcpUrl) {
+    const flags = spec.addFlags ?? [];
+    return spec.urlStyle === 'positional'
+        ? ['mcp', 'add', ...flags, 'tinyfish', mcpUrl]
+        : ['mcp', 'add', 'tinyfish', '--url', mcpUrl, ...flags];
+}
+function specKeyAuth(spec) {
+    const { header, keyEnvFlag, keyAddFlags } = spec;
+    if (keyEnvFlag) {
+        return {
+            envVar: TINYFISH_API_KEY_VAR,
+            addArgs: (mcpUrl) => [...specAddArgs(spec, mcpUrl), keyEnvFlag, TINYFISH_API_KEY_VAR],
+        };
+    }
+    if (keyAddFlags) {
+        return { addArgs: (mcpUrl) => [...specAddArgs(spec, mcpUrl), ...keyAddFlags] };
+    }
+    if (!header)
+        return undefined;
+    const value = (apiKey) => `${header.name}${header.sep}${header.valuePrefix ?? ''}${apiKey}`;
+    if (header.viaEnv) {
+        return {
+            envVar: TINYFISH_API_KEY_VAR,
+            addArgs: (mcpUrl) => [
+                ...specAddArgs(spec, mcpUrl),
+                '--header',
+                value(`\${${TINYFISH_API_KEY_VAR}}`),
+            ],
+        };
+    }
+    return {
+        addArgs: (mcpUrl, apiKey) => [...specAddArgs(spec, mcpUrl), '--header', value(apiKey)],
+    };
+}
+/** Descriptor behaviour the spec cannot hold; every other field is spec data. */
+const HARNESS_OVERRIDES = {
+    codex: { detachedLaunch: launchCodexWalkthrough },
+    hermes: {
+        launchWalkthrough: launchHermesWalkthrough,
+        extraPostInstall: installHermesWebPlugin,
+        seedKey: seedHermesKey,
     },
-    keyAuth: headerKeyAuth,
-    // `opencode mcp add` upserts by name and there is no `opencode mcp remove`, so no cleanup step.
-    removals: [],
-    // OpenCode writes ~/.config/opencode/opencode.json itself; `mcp auth` is the separate OAuth step.
-    addArgs: (mcpUrl) => urlAddArgs(mcpUrl),
-    loginArgs: ['mcp', 'auth', 'tinyfish'],
-    launchWalkthrough: launchOpencode,
-    postConnectNote: OPENCODE_MODEL_NOTE,
+    opencode: { launchWalkthrough: launchOpencode },
 };
-/** Every native MCP client. Derive from this, so a new harness cannot be missed. */
-export const NATIVE_MCP_CLIENTS = [
-    CLAUDE_CODE,
-    CODEX,
-    GROK,
-    HERMES,
-    OPENCODE,
-];
+function toNativeClient(harness) {
+    const spec = harnessSpec(harness);
+    if (!spec.supportCheck)
+        throw new Error(`${harness} has no supportCheck to probe`);
+    const overrides = HARNESS_OVERRIDES[harness] ?? {};
+    const keyed = specKeyAuth(spec);
+    const keyAuth = keyed && { ...keyed, seedKey: overrides.seedKey };
+    const base = {
+        command: spec.command,
+        connectClient: harness,
+        displayName: spec.displayName,
+        supportCheck: spec.supportCheck,
+        skillAgent: spec.skillAgent,
+        nonInteractiveAdd: spec.nonInteractiveAdd,
+        keyAuth,
+        signInHint: spec.signInHint,
+        degradedAuthNotes: spec.degradedAuthNotes,
+        removals: spec.removals ?? [
+            {
+                args: ['mcp', 'remove', 'tinyfish'],
+                label: `TinyFish registration from ${spec.displayName}`,
+            },
+        ],
+        launchWalkthrough: overrides.launchWalkthrough,
+        detachedLaunch: overrides.detachedLaunch,
+        postConnectNote: spec.postConnectNote,
+        extraPostInstall: overrides.extraPostInstall,
+        uninstallExtra: spec.uninstallExtra,
+    };
+    if (spec.keyRequired) {
+        if (!keyAuth)
+            throw new Error(`${harness} takes only a key but has no keyed add`);
+        return { ...base, keyRequired: true, keyAuth };
+    }
+    return {
+        ...base,
+        loginArgs: spec.loginArgs,
+        addArgs: (mcpUrl) => specAddArgs(spec, mcpUrl),
+    };
+}
+export const NATIVE_MCP_CLIENTS = NATIVE_HARNESSES.map(toNativeClient);
 /** Native descriptor by harness id; Cursor and OpenClaw have none. */
 export const NATIVE_BY_HARNESS = new Map(NATIVE_MCP_CLIENTS.map((client) => [client.connectClient, client]));
+function nativeClient(harness) {
+    const client = NATIVE_BY_HARNESS.get(harness);
+    if (!client)
+        throw new Error(`${harness} is not a native MCP client`);
+    return client;
+}
+export const CLAUDE_CODE = nativeClient('claude-code');
+export const CODEX = nativeClient('codex');
+export const GROK = nativeClient('grok');
+export const HERMES = nativeClient('hermes');
+export const OPENCODE = nativeClient('opencode');
 export const OPENCLAW = {
-    command: 'openclaw',
-    displayName: 'OpenClaw',
-    supportCheck: {
-        args: ['skills', 'install', '--help'],
-        patterns: [/--global(?:\s|$)/, /--acknowledge-clawhub-risk(?:\s|$)/],
-        unavailableMessage: OPENCLAW_SKILL_UNAVAILABLE_MESSAGE,
-    },
-};
-/** Required booleans: a new harness or new flag fails to compile undecided. */
-export const HARNESS_CAPABILITIES = {
-    'claude-code': {
-        signInViaCliLogin: false,
-        canVerifyAuth: false,
-        keyHeldByCli: false,
-        cliWritesConfig: false,
-        authDeferredAtInstall: false,
-    },
-    codex: {
-        signInViaCliLogin: false,
-        canVerifyAuth: false,
-        keyHeldByCli: false,
-        cliWritesConfig: false,
-        // TODO(PF-3580): connect now probes Codex sign-in, so this over-warns a signed-in install.
-        authDeferredAtInstall: true,
-    },
-    cursor: {
-        signInViaCliLogin: false,
-        canVerifyAuth: true,
-        keyHeldByCli: true,
-        cliWritesConfig: true,
-        authDeferredAtInstall: false,
-    },
-    grok: {
-        signInViaCliLogin: false,
-        canVerifyAuth: false,
-        keyHeldByCli: false,
-        cliWritesConfig: false,
-        authDeferredAtInstall: false,
-    },
-    hermes: {
-        signInViaCliLogin: false,
-        // Stays false: keyed already covers auth; true breaks keyless installs.
-        canVerifyAuth: false,
-        keyHeldByCli: true,
-        cliWritesConfig: false,
-        authDeferredAtInstall: false,
-    },
-    openclaw: {
-        signInViaCliLogin: true,
-        canVerifyAuth: true,
-        keyHeldByCli: true,
-        cliWritesConfig: false,
-        authDeferredAtInstall: false,
-    },
-    opencode: {
-        signInViaCliLogin: false,
-        canVerifyAuth: false,
-        keyHeldByCli: false,
-        cliWritesConfig: false,
-        authDeferredAtInstall: false,
-    },
+    command: HARNESS_SPECS.openclaw.command,
+    displayName: HARNESS_SPECS.openclaw.displayName,
+    supportCheck: HARNESS_SPECS.openclaw.supportCheck,
 };
+export const HARNESS_CAPABILITIES = Object.fromEntries(ALL_HARNESSES.map((harness) => {
+    const spec = harnessSpec(harness);
+    return [
+        harness,
+        {
+            signInViaCliLogin: spec.signInViaCliLogin,
+            canVerifyAuth: spec.canVerifyAuth,
+            keyHeldByCli: spec.keyHeldByCli,
+            cliWritesConfig: spec.cliWritesConfig,
+            authDeferredAtInstall: spec.authDeferredAtInstall,
+        },
+    ];
+}));
 function printPromptForHandoff(displayName, command, prompt, reason) {
     // "set up", not "connected": sign-in can still be deferred here.
     errLine(`TinyFish is set up in ${displayName}.`);

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

@@ -1,6 +1,7 @@
 import { AuthMode } from './harness-detect.js';
+import type { Harness, HarnessSupportCheck } from './harness-spec.js';
 export declare const NON_INTERACTIVE_TIMEOUT_MS = 10000;
-export type AgentClient = 'claude-code' | 'codex' | 'cursor' | 'grok' | 'hermes' | 'openclaw' | 'opencode';
+export type AgentClient = Harness;
 type ConnectStage = 'started' | 'checkpoint' | 'completed' | 'failed' | 'aborted' | 'post_install_failed';
 export type ConnectFailureStage = 'prerequisite_check' | 'registration_cleanup' | 'registration' | 'registration_or_authentication' | 'client_oauth' | 'cli_install' | 'skill_install' | 'plugin_install' | 'authentication' | 'walkthrough_launch' | 'cli_verification';
 export declare const CONNECT_FAILURE_REASONS: readonly ["harness_not_installed", "harness_command_unsupported", "harness_too_old", "key_auth_unsupported", "command_not_found", "timeout", "spawn_error", "nonzero_exit", "invalid_config", "user_abandoned", "process_terminated", "unexpected_error"];
@@ -87,16 +88,7 @@ export declare function runGuarded(state: ConnectRunState, telemetry: ConnectTel
 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[];
-        /** Missing → this install cannot take a stored key; fall back to OAuth. */
-        keyAuthPattern?: RegExp;
-        unavailableMessage: string;
-    };
+    supportCheck: HarnessSupportCheck;
 }
 export declare function requireCommandSupport(client: SupportedCommand): {
     optionalSupported: boolean;

package/dist/lib/constants.d.ts

@@ -12,3 +12,5 @@ export declare const API_URL_OVERRIDE: string | undefined;
 export declare function getDashboardUrl(source?: string): string;
 export declare const DASHBOARD_URL: string;
 export declare const HARNESS_PROBE_TIMEOUT_MS = 15000;
+/** Hermes' own id for the TinyFish web plugin. */
+export declare const HERMES_PLUGIN_NAME = "tinyfish";

package/dist/lib/constants.js

@@ -49,3 +49,5 @@ export function getDashboardUrl(source = DEFAULT_DASHBOARD_SOURCE) {
 }
 export const DASHBOARD_URL = getDashboardUrl();
 export const HARNESS_PROBE_TIMEOUT_MS = 15_000;
+/** Hermes' own id for the TinyFish web plugin. */
+export const HERMES_PLUGIN_NAME = 'tinyfish';

package/dist/lib/harness-detect.d.ts

@@ -1,7 +1,6 @@
-export declare const ALL_HARNESSES: readonly ["claude-code", "codex", "cursor", "grok", "hermes", "openclaw", "opencode"];
-export type Harness = (typeof ALL_HARNESSES)[number];
+import { ALL_HARNESSES, type Harness } from './harness-spec.js';
+export { ALL_HARNESSES, type Harness };
 export declare const HARNESS_DISPLAY_NAMES: Record<Harness, string>;
-/** MCP config is read at startup, so a running harness needs this to see TinyFish. */
 export declare const RELOAD_ACTION: Record<Harness, string>;
 export declare enum Registered {
     Yes = "yes",
@@ -16,7 +15,7 @@ export declare enum AuthMode {
 export declare const HARNESS_COMMANDS: Record<Harness, string>;
 export declare function commandOnPath(command: string): boolean;
 export declare function harnessConfigPath(harness: Harness): string;
-/** For reason strings that name a location; keeps them in sync with the table above. */
+/** For reason strings that name a location; keeps them in sync with the spec. */
 export declare function harnessDisplayPath(harness: Harness): string;
 export interface HarnessDetection {
     harness: Harness;

package/dist/lib/harness-detect.js

@@ -2,35 +2,10 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import which from 'which';
-export const ALL_HARNESSES = [
-    'claude-code',
-    'codex',
-    'cursor',
-    'grok',
-    'hermes',
-    'openclaw',
-    'opencode',
-];
-export const HARNESS_DISPLAY_NAMES = {
-    'claude-code': 'Claude Code',
-    codex: 'Codex',
-    cursor: 'Cursor',
-    grok: 'Grok',
-    hermes: 'Hermes',
-    openclaw: 'OpenClaw',
-    opencode: 'OpenCode',
-};
-/** MCP config is read at startup, so a running harness needs this to see TinyFish. */
-export const RELOAD_ACTION = {
-    'claude-code': 'restart it',
-    codex: 'restart it',
-    // docs.x.ai/build/features/mcp-servers: `r` in /mcps rereads the config.
-    grok: 'run /mcps and press r',
-    hermes: 'restart it',
-    openclaw: 'restart it',
-    opencode: 'restart it',
-    cursor: 'reload the window',
-};
+import { ALL_HARNESSES, harnessSpec } from './harness-spec.js';
+export { ALL_HARNESSES };
+export const HARNESS_DISPLAY_NAMES = Object.fromEntries(ALL_HARNESSES.map((harness) => [harness, harnessSpec(harness).displayName]));
+export const RELOAD_ACTION = Object.fromEntries(ALL_HARNESSES.map((harness) => [harness, harnessSpec(harness).reloadAction]));
 // Values are the wire contract; the report schema derives from these.
 export var Registered;
 (function (Registered) {
@@ -44,26 +19,9 @@ export var AuthMode;
     AuthMode["OAuth"] = "oauth";
     AuthMode["Unknown"] = "unknown";
 })(AuthMode || (AuthMode = {}));
-const CONFIG_DIRS = {
-    'claude-code': '.claude',
-    codex: '.codex',
-    cursor: '.cursor',
-    grok: '.grok',
-    hermes: '.hermes',
-    openclaw: '.openclaw',
-    opencode: '.config/opencode',
-};
 // Harness id is not the binary name (cursor-agent).
 // TODO(PF-3668): a same-named non-harness binary still reads as installed.
-export const HARNESS_COMMANDS = {
-    'claude-code': 'claude',
-    codex: 'codex',
-    cursor: 'cursor-agent',
-    grok: 'grok',
-    hermes: 'hermes',
-    openclaw: 'openclaw',
-    opencode: 'opencode',
-};
+export const HARNESS_COMMANDS = Object.fromEntries(ALL_HARNESSES.map((harness) => [harness, harnessSpec(harness).command]));
 // cross-spawn resolves the same way, so detection cannot disagree with the spawn.
 export function commandOnPath(command) {
     try {
@@ -74,11 +32,11 @@ export function commandOnPath(command) {
     }
 }
 export function harnessConfigPath(harness) {
-    return path.join(os.homedir(), CONFIG_DIRS[harness]); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
+    return path.join(os.homedir(), harnessSpec(harness).configDir); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
 }
-/** For reason strings that name a location; keeps them in sync with the table above. */
+/** For reason strings that name a location; keeps them in sync with the spec. */
 export function harnessDisplayPath(harness) {
-    return `~/${CONFIG_DIRS[harness]}`;
+    return `~/${harnessSpec(harness).configDir}`;
 }
 export function detectInstalledHarnesses() {
     return ALL_HARNESSES.map((harness) => {

package/dist/lib/harness-spec.d.ts

@@ -0,0 +1,251 @@
+/** The `skills` CLI's own agent names, not ours. */
+export type SkillAgent = 'claude-code' | 'codex' | 'cursor' | 'hermes-agent' | 'opencode';
+export interface HarnessSupportCheck {
+    args: string[];
+    /** Missing → nothing can work; setup fails. */
+    patterns: RegExp[];
+    /** Missing → degrade to key or deferred auth, never refuse. */
+    optionalPatterns?: RegExp[];
+    /** Missing → this install cannot take a stored key; fall back to OAuth. */
+    keyAuthPattern?: RegExp;
+    unavailableMessage: string;
+}
+/** One entry per harness: every per-harness fact, and no behaviour. */
+export interface HarnessSpec {
+    command: string;
+    displayName: string;
+    /** Home-relative; existing dir means the harness ran here once. */
+    configDir: string;
+    /** MCP config is read at startup; a running harness needs this to see TinyFish. */
+    reloadAction: string;
+    skillAgent?: SkillAgent;
+    /** Absent for Cursor: its connect writes mcp.json, no binary probe. */
+    supportCheck?: HarnessSupportCheck;
+    /** Capturable: this `mcp add` never runs OAuth inline; unset stays inherited. */
+    nonInteractiveAdd?: true;
+    /** Present only on native MCP harnesses; absent means connect is an override. */
+    urlStyle?: 'flag' | 'positional';
+    /** "positional": before `tinyfish <url>`. "flag": after `--url <url>`. */
+    addFlags?: string[];
+    /** Keyed adds append `--header` built from these parts. */
+    header?: {
+        name: string;
+        sep: ': ' | '=';
+        valuePrefix?: string;
+        viaEnv?: boolean;
+    };
+    /** Keyed adds append this flag plus the env var name (Codex). */
+    keyEnvFlag?: string;
+    /** Keyed adds append these flags; the key itself is seeded elsewhere (Hermes). */
+    keyAddFlags?: string[];
+    /** No sign-in exists here, so connect refuses a keyless install (Hermes). */
+    keyRequired?: true;
+    loginArgs?: string[];
+    /** Default: one `mcp remove tinyfish` labeled from displayName. */
+    removals?: {
+        args: string[];
+        label: string;
+    }[];
+    /** Extra --uninstall row beyond `removals`; never runs pre-add. */
+    uninstallExtra?: {
+        args: string[];
+        label: string;
+    };
+    /** Shown when a keyless install leaves sign-in to the harness. */
+    signInHint?: string;
+    /** Replaces the `loginArgs` step when `supportCheck.optionalPatterns` miss. */
+    degradedAuthNotes?: {
+        keyed: string;
+        deferred: string;
+    };
+    /** Printed after a successful connect, on both the launch and non-launch paths. */
+    postConnectNote?: string;
+    /** Sign-in is the CLI's own interactive `tinyfish auth login`. */
+    signInViaCliLogin: boolean;
+    /** Stored-key auth verification works against this harness's config. */
+    canVerifyAuth: boolean;
+    /** The CLI holds or writes the key; no harness `mcp add` carries it. */
+    keyHeldByCli: boolean;
+    /** Connect writes the MCP config file; no harness binary is spawned. */
+    cliWritesConfig: boolean;
+    /** `mcp add` succeeds unauthenticated; OAuth lands at first tool use. */
+    authDeferredAtInstall: boolean;
+}
+/** One entry per harness; every per-harness list derives from it. */
+export declare const HARNESS_SPECS: {
+    'claude-code': {
+        command: string;
+        displayName: string;
+        configDir: string;
+        reloadAction: string;
+        skillAgent: "claude-code";
+        nonInteractiveAdd: true;
+        supportCheck: {
+            args: string[];
+            patterns: RegExp[];
+            optionalPatterns: RegExp[];
+            keyAuthPattern: RegExp;
+            unavailableMessage: string;
+        };
+        urlStyle: "positional";
+        addFlags: string[];
+        header: {
+            name: string;
+            sep: ": ";
+        };
+        loginArgs: string[];
+        degradedAuthNotes: {
+            keyed: string;
+            deferred: string;
+        };
+        removals: {
+            args: string[];
+            label: string;
+        }[];
+        signInViaCliLogin: false;
+        canVerifyAuth: false;
+        keyHeldByCli: false;
+        cliWritesConfig: false;
+        authDeferredAtInstall: false;
+    };
+    codex: {
+        command: string;
+        displayName: string;
+        configDir: string;
+        reloadAction: string;
+        skillAgent: "codex";
+        supportCheck: {
+            args: string[];
+            patterns: RegExp[];
+            optionalPatterns: RegExp[];
+            keyAuthPattern: RegExp;
+            unavailableMessage: string;
+        };
+        urlStyle: "flag";
+        keyEnvFlag: string;
+        degradedAuthNotes: {
+            keyed: string;
+            deferred: string;
+        };
+        loginArgs: string[];
+        signInViaCliLogin: false;
+        canVerifyAuth: false;
+        keyHeldByCli: false;
+        cliWritesConfig: false;
+        authDeferredAtInstall: true;
+    };
+    cursor: {
+        command: string;
+        displayName: string;
+        configDir: string;
+        reloadAction: string;
+        skillAgent: "cursor";
+        signInViaCliLogin: false;
+        canVerifyAuth: true;
+        keyHeldByCli: true;
+        cliWritesConfig: true;
+        authDeferredAtInstall: false;
+    };
+    grok: {
+        command: string;
+        displayName: string;
+        configDir: string;
+        reloadAction: string;
+        nonInteractiveAdd: true;
+        supportCheck: {
+            args: string[];
+            patterns: RegExp[];
+            keyAuthPattern: RegExp;
+            unavailableMessage: string;
+        };
+        urlStyle: "positional";
+        addFlags: string[];
+        header: {
+            name: string;
+            sep: ": ";
+            valuePrefix: string;
+            viaEnv: true;
+        };
+        signInHint: string;
+        signInViaCliLogin: false;
+        canVerifyAuth: false;
+        keyHeldByCli: false;
+        cliWritesConfig: false;
+        authDeferredAtInstall: false;
+    };
+    hermes: {
+        command: string;
+        displayName: string;
+        configDir: string;
+        reloadAction: string;
+        skillAgent: "hermes-agent";
+        keyRequired: true;
+        supportCheck: {
+            args: string[];
+            patterns: RegExp[];
+            keyAuthPattern: RegExp;
+            unavailableMessage: string;
+        };
+        urlStyle: "flag";
+        keyAddFlags: string[];
+        uninstallExtra: {
+            args: string[];
+            label: string;
+        };
+        postConnectNote: string;
+        signInViaCliLogin: false;
+        canVerifyAuth: false;
+        keyHeldByCli: true;
+        cliWritesConfig: false;
+        authDeferredAtInstall: false;
+    };
+    openclaw: {
+        command: string;
+        displayName: string;
+        configDir: string;
+        reloadAction: string;
+        supportCheck: {
+            args: string[];
+            patterns: RegExp[];
+            unavailableMessage: string;
+        };
+        signInViaCliLogin: true;
+        canVerifyAuth: true;
+        keyHeldByCli: true;
+        cliWritesConfig: false;
+        authDeferredAtInstall: false;
+    };
+    opencode: {
+        command: string;
+        displayName: string;
+        configDir: string;
+        reloadAction: string;
+        skillAgent: "opencode";
+        nonInteractiveAdd: true;
+        supportCheck: {
+            args: string[];
+            patterns: RegExp[];
+            keyAuthPattern: RegExp;
+            unavailableMessage: string;
+        };
+        urlStyle: "flag";
+        header: {
+            name: string;
+            sep: "=";
+        };
+        loginArgs: string[];
+        removals: never[];
+        postConnectNote: string;
+        signInViaCliLogin: false;
+        canVerifyAuth: false;
+        keyHeldByCli: false;
+        cliWritesConfig: false;
+        authDeferredAtInstall: false;
+    };
+};
+/** Derived from spec keys; one entry extends every union. */
+export type Harness = keyof typeof HARNESS_SPECS;
+export declare const ALL_HARNESSES: readonly Harness[];
+export declare function harnessSpec(harness: Harness): HarnessSpec;
+/** Native MCP harnesses carry add-generation fields; the rest override connect. */
+export declare const NATIVE_HARNESSES: ("openclaw" | "grok" | "cursor" | "codex" | "hermes" | "opencode" | "claude-code")[];

package/dist/lib/harness-spec.js

@@ -0,0 +1,235 @@
+import { HERMES_PLUGIN_NAME } from './constants.js';
+// 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. Already have a TinyFish API key? ' +
+    'Run `tinyfish connect claude-code --api-key <key>` instead.';
+const CODEX_MCP_URL_UNAVAILABLE_MESSAGE = 'Could not confirm this Codex installation supports remote MCP servers: `codex mcp add ' +
+    '--help` did not list `--url`. Update Codex and retry, or add TinyFish manually with ' +
+    '`codex mcp add`.' +
+    SUPPORT_CHECK_DEBUG_HINT;
+const CODEX_KEYED_FALLBACK_NOTE = 'Using your stored TinyFish API key: this Codex cannot report whether an OAuth sign-in ' +
+    'finished, so no browser sign-in is attempted.';
+const CODEX_DEFERRED_AUTH_NOTE = 'TinyFish is registered in Codex but not signed in: this Codex predates reliable sign-in ' +
+    'reporting. Run `codex mcp login tinyfish` to sign in, or update Codex with ' +
+    '`npm install -g @openai/codex@latest` for one-command sign-in.';
+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 GROK_HTTP_UNAVAILABLE_MESSAGE = 'Could not confirm this Grok installation supports remote MCP servers: `grok mcp add --help` ' +
+    'did not list `--transport`. Update Grok and retry, or add TinyFish manually with ' +
+    '`grok mcp add`.' +
+    SUPPORT_CHECK_DEBUG_HINT;
+// Grok has no `mcp login`; sign-in only happens inside the TUI. No key nudge here: a revoked
+// key leaves Grok with no OAuth fallback, and doctor cannot spot that yet (PF-3618).
+const GROK_SIGN_IN_HINT = 'TinyFish is registered in Grok. Open Grok, run `/mcps`, select tinyfish, and press `i` to ' +
+    'sign in.';
+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 HERMES_RESTART_NOTE = 'Restart your Hermes session to pick up TinyFish — Hermes discovers MCP servers at startup.';
+const HEADER_FLAG = /(?:^|\s)--header(?:[\s<=]|$)/m;
+/** One entry per harness; every per-harness list derives from it. */
+export const HARNESS_SPECS = {
+    'claude-code': {
+        command: 'claude',
+        displayName: 'Claude Code',
+        configDir: '.claude',
+        reloadAction: 'restart it',
+        skillAgent: 'claude-code',
+        nonInteractiveAdd: true,
+        supportCheck: {
+            args: ['mcp', '--help'],
+            patterns: [/^\s*add(?:\s|\[)/m],
+            optionalPatterns: [/^\s*login(?:\s|\[)/m],
+            keyAuthPattern: HEADER_FLAG,
+            unavailableMessage: MCP_ADD_UNAVAILABLE_MESSAGE,
+        },
+        urlStyle: 'positional',
+        addFlags: ['--scope', 'user', '--transport', 'http'],
+        header: { name: 'X-API-Key', sep: ': ' },
+        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',
+            },
+        ],
+        signInViaCliLogin: false,
+        canVerifyAuth: false,
+        keyHeldByCli: false,
+        cliWritesConfig: false,
+        authDeferredAtInstall: false,
+    },
+    codex: {
+        command: 'codex',
+        displayName: 'Codex',
+        configDir: '.codex',
+        reloadAction: 'restart it',
+        skillAgent: 'codex',
+        supportCheck: {
+            args: ['mcp', 'add', '--help'],
+            patterns: [/--url(?:[\s<=]|$)/m],
+            // Codex before ~0.142 reports `o_auth` for a server it never signed in to, so the
+            // sign-in probe lies; `--oauth-resource` is the only marker separating the two.
+            optionalPatterns: [/--oauth-resource(?:[\s<=]|$)/m],
+            keyAuthPattern: /(?:^|\s)--bearer-token-env-var(?:[\s<=]|$)/m,
+            unavailableMessage: CODEX_MCP_URL_UNAVAILABLE_MESSAGE,
+        },
+        urlStyle: 'flag',
+        // Codex has no `--header`; the MCP server takes a key as `Bearer sk-…`.
+        keyEnvFlag: '--bearer-token-env-var',
+        degradedAuthNotes: { keyed: CODEX_KEYED_FALLBACK_NOTE, deferred: CODEX_DEFERRED_AUTH_NOTE },
+        // `--oauth-resource` duplicates the resource Codex discovers; Clerk rejects both.
+        // `mcp add` still runs OAuth inline, so `loginArgs` stays a retry.
+        loginArgs: ['mcp', 'login', 'tinyfish'],
+        signInViaCliLogin: false,
+        canVerifyAuth: false,
+        keyHeldByCli: false,
+        cliWritesConfig: false,
+        // TODO(PF-3580): connect now probes Codex sign-in, so this over-warns a signed-in install.
+        authDeferredAtInstall: true,
+    },
+    cursor: {
+        command: 'cursor-agent',
+        displayName: 'Cursor',
+        configDir: '.cursor',
+        reloadAction: 'reload the window',
+        skillAgent: 'cursor',
+        signInViaCliLogin: false,
+        canVerifyAuth: true,
+        keyHeldByCli: true,
+        cliWritesConfig: true,
+        authDeferredAtInstall: false,
+    },
+    grok: {
+        command: 'grok',
+        displayName: 'Grok',
+        configDir: '.grok',
+        // docs.x.ai/build/features/mcp-servers: `r` in /mcps rereads the config.
+        reloadAction: 'run /mcps and press r',
+        nonInteractiveAdd: true,
+        supportCheck: {
+            args: ['mcp', 'add', '--help'],
+            patterns: [/--transport(?:[\s<=]|$)/m],
+            keyAuthPattern: HEADER_FLAG,
+            unavailableMessage: GROK_HTTP_UNAVAILABLE_MESSAGE,
+        },
+        urlStyle: 'positional',
+        addFlags: ['--transport', 'http'],
+        // X-API-Key is dropped whenever the server advertises OAuth metadata; Bearer is not.
+        // Grok expands `${VAR}` in headers at load, so the key stays out of argv and config.toml.
+        header: { name: 'Authorization', sep: ': ', valuePrefix: 'Bearer ', viaEnv: true },
+        signInHint: GROK_SIGN_IN_HINT,
+        signInViaCliLogin: false,
+        canVerifyAuth: false,
+        keyHeldByCli: false,
+        cliWritesConfig: false,
+        authDeferredAtInstall: false,
+    },
+    hermes: {
+        command: 'hermes',
+        displayName: 'Hermes',
+        configDir: '.hermes',
+        reloadAction: 'restart it',
+        skillAgent: 'hermes-agent',
+        keyRequired: true,
+        supportCheck: {
+            args: ['mcp', 'add', '--help'],
+            patterns: [/--auth\s+\{[^}]*oauth[^}]*\}/],
+            keyAuthPattern: /--auth\s+\{[^}]*header[^}]*\}/,
+            unavailableMessage: HERMES_OAUTH_UNAVAILABLE_MESSAGE,
+        },
+        urlStyle: 'flag',
+        // No `header`: the key goes into Hermes' .env, and `--auth header` reads it from there.
+        keyAddFlags: ['--auth', 'header'],
+        uninstallExtra: {
+            args: ['plugins', 'uninstall', HERMES_PLUGIN_NAME],
+            label: 'TinyFish web plugin from Hermes',
+        },
+        postConnectNote: HERMES_RESTART_NOTE,
+        signInViaCliLogin: false,
+        // Stays false: keyed already covers auth; true breaks keyless installs.
+        canVerifyAuth: false,
+        keyHeldByCli: true,
+        cliWritesConfig: false,
+        authDeferredAtInstall: false,
+    },
+    openclaw: {
+        command: 'openclaw',
+        displayName: 'OpenClaw',
+        configDir: '.openclaw',
+        reloadAction: 'restart it',
+        supportCheck: {
+            args: ['skills', 'install', '--help'],
+            patterns: [/--global(?:\s|$)/, /--acknowledge-clawhub-risk(?:\s|$)/],
+            unavailableMessage: OPENCLAW_SKILL_UNAVAILABLE_MESSAGE,
+        },
+        signInViaCliLogin: true,
+        canVerifyAuth: true,
+        keyHeldByCli: true,
+        cliWritesConfig: false,
+        authDeferredAtInstall: false,
+    },
+    opencode: {
+        command: 'opencode',
+        displayName: 'OpenCode',
+        configDir: '.config/opencode',
+        reloadAction: 'restart it',
+        skillAgent: 'opencode',
+        nonInteractiveAdd: true,
+        supportCheck: {
+            args: ['mcp', 'add', '--help'],
+            patterns: [/--url(?:\s|$)/m],
+            keyAuthPattern: HEADER_FLAG,
+            unavailableMessage: OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE,
+        },
+        urlStyle: 'flag',
+        // OpenCode takes `--header NAME=VALUE`, not Claude Code's `NAME: VALUE`.
+        header: { name: 'X-API-Key', sep: '=' },
+        // OpenCode writes its config itself; `mcp auth` is the separate OAuth step.
+        loginArgs: ['mcp', 'auth', 'tinyfish'],
+        // `opencode mcp add` upserts by name and ships no `mcp remove`.
+        removals: [],
+        postConnectNote: OPENCODE_MODEL_NOTE,
+        signInViaCliLogin: false,
+        canVerifyAuth: false,
+        keyHeldByCli: false,
+        cliWritesConfig: false,
+        authDeferredAtInstall: false,
+    },
+};
+export const ALL_HARNESSES = Object.keys(HARNESS_SPECS);
+export function harnessSpec(harness) {
+    return HARNESS_SPECS[harness];
+}
+/** Native MCP harnesses carry add-generation fields; the rest override connect. */
+export const NATIVE_HARNESSES = ALL_HARNESSES.filter((harness) => harnessSpec(harness).urlStyle !== undefined);

package/dist/lib/hermes-plugin.d.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod';
 import { type InstallOptions } from './cli-install.js';
 export declare const HERMES_PLUGIN_SHA = "496cd63fefd982bbaa8a85ce78ef2270d700984f";
-export declare const HERMES_PLUGIN_NAME = "tinyfish";
 export declare const HERMES_PLUGIN_MANUAL_INSTALL = "hermes plugins install tinyfish-io/tinyfish-web-agent-integrations/hermes --ref 496cd63fefd982bbaa8a85ce78ef2270d700984f --enable";
 export declare function installHermesPlugin(home: string, apiKey: string, { verbose }: Pick<InstallOptions, 'verbose'>): void;
 /** After install only: backends must never name an absent provider. */

package/dist/lib/hermes-plugin.js

@@ -11,7 +11,6 @@ import { errLine } from './output.js';
 // Bump per CLI release.
 export const HERMES_PLUGIN_SHA = '496cd63fefd982bbaa8a85ce78ef2270d700984f';
 // Manifest `name:`, not the repo subdir; `plugins uninstall` keys on it.
-export const HERMES_PLUGIN_NAME = 'tinyfish';
 const PLUGIN_SOURCE = 'tinyfish-io/tinyfish-web-agent-integrations/hermes';
 const PLUGIN_REPO_URL = 'https://github.com/tinyfish-io/tinyfish-web-agent-integrations.git';
 export const HERMES_PLUGIN_MANUAL_INSTALL = `hermes plugins install ${PLUGIN_SOURCE} --ref ${HERMES_PLUGIN_SHA} --enable`;

package/dist/lib/setup-telemetry.d.ts

@@ -79,7 +79,7 @@ export type UpgradeScope = 'both' | 'cli' | 'skill';
 /** `toVersion` is null when the run was interrupted or the installed version could not be read. */
 export declare function sendUpgradeCompleted(fromVersion: string, toVersion: string | null, outcome: UpgradeOutcome, scope: UpgradeScope, apiKey?: string): Promise<void>;
 export declare function sendSetupCompleted(mcpUrl: string, harnesses: HarnessResult[], apiKey?: string, mode?: SetupMode, attemptId?: string): Promise<void>;
-export declare const DOCTOR_HARNESS_SCOPES: readonly ["all", "claude-code", "codex", "cursor", "grok", "hermes", "openclaw", "opencode"];
+export declare const DOCTOR_HARNESS_SCOPES: readonly ["all", ...("openclaw" | "grok" | "cursor" | "codex" | "hermes" | "opencode" | "claude-code")[]];
 export declare const doctorCompletedPayloadSchema: z.ZodObject<{
     schema_version: z.ZodInt;
     cli_version: z.ZodString;

package/package.json

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