@tiny-fish/cli 0.34.1-next.282 → 0.34.1-next.284

package/dist/commands/connect.js

@@ -346,6 +346,16 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
                 telemetry.track('checkpoint', { phase: 'skill_installed' });
             });
         }
+        const extraPostInstall = client.extraPostInstall;
+        if (extraPostInstall) {
+            await attempt('plugin_install', () => {
+                extraPostInstall({
+                    apiKey: validatedApiKey(options.apiKey),
+                    verbose: options.verbose ?? false,
+                });
+                telemetry.track('checkpoint', { phase: 'plugin_installed' });
+            });
+        }
         // Before auth: a failed sign-in must not lose the harness record.
         saveConnectContext(client.connectClient, telemetry.attemptId, state.authMode);
         await attempt('authentication', () => {

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

@@ -69,6 +69,11 @@ interface BaseMcpClient extends SupportedCommand {
     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;
+        verbose: boolean;
+    }) => void;
 }
 /** Keyless installs use this argv; the harness signs itself in. */
 export interface OauthCapableMcpClient extends BaseMcpClient {

package/dist/lib/connect-clients.js

@@ -7,6 +7,7 @@ import { ConnectStepError, spawnStepError, } from './connect-runtime.js';
 import { TINYFISH_API_KEY_VAR } from './constants.js';
 import { HERMES_KEY_VAR, captureHermesKeyRestore, hermesEnvPath, resolveHermesHome, writeHermesKey, } from './hermes-env.js';
 import { hermesConfigPath, readHermesEntry } from './hermes-config.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.';
@@ -259,12 +260,16 @@ export function hermesRegistrationEnabled(home) {
     // The tag keeps the path-bearing prose out of telemetry.
     return { ok: false, detail, tag: `hermes_entry_${entry.state}` };
 }
-function seedHermesKey(apiKey) {
+// A plain Error settles unexpected_error; cli_connect_stage is load-bearing.
+function requireHermesHome() {
     const home = resolveHermesHome();
-    // A plain Error settles unexpected_error; cli_connect_stage is load-bearing.
     if (!home) {
         throw new ConnectStepError("Could not determine Hermes' home directory from `hermes dump`", 'invalid_config', { failureDetail: 'hermes_home_undetermined' });
     }
+    return home;
+}
+function seedHermesKey(apiKey) {
+    const home = requireHermesHome();
     const restore = captureHermesKeyRestore(home);
     writeHermesKey(home, apiKey);
     return {
@@ -287,6 +292,15 @@ function rollbackHermesKey(home, restore) {
         warnLine(`Could not restore ${HERMES_KEY_VAR} in ${hermesEnvPath(home)}; check it by hand.`);
     }
 }
+// Hermes is keyRequired; a missing key here is a resolution bug.
+function installHermesWebPlugin({ apiKey, verbose }) {
+    if (!apiKey) {
+        throw new ConnectStepError('No TinyFish API key was available to install the Hermes web plugin', 'invalid_config');
+    }
+    const home = requireHermesHome();
+    installHermesPlugin(home, apiKey, { verbose });
+    setHermesWebBackends(home);
+}
 export const HERMES = {
     command: 'hermes',
     connectClient: 'hermes',
@@ -305,6 +319,7 @@ export const HERMES = {
         seedKey: seedHermesKey,
     },
     removals: [{ args: ['mcp', 'remove', 'tinyfish'], label: 'TinyFish registration from Hermes' }],
+    extraPostInstall: installHermesWebPlugin,
     launchWalkthrough: launchHermesWalkthrough,
     postConnectNote: 'Restart your Hermes session to pick up TinyFish — Hermes discovers MCP servers at startup.',
 };

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

@@ -2,11 +2,11 @@ import { AuthMode } from './harness-detect.js';
 export declare const NON_INTERACTIVE_TIMEOUT_MS = 10000;
 export type AgentClient = 'claude-code' | 'codex' | 'cursor' | 'grok' | 'hermes' | 'openclaw' | 'opencode';
 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' | 'authentication' | 'walkthrough_launch' | 'cli_verification';
+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"];
 export type ConnectFailureReason = (typeof CONNECT_FAILURE_REASONS)[number];
 export type ConnectAuthMode = Exclude<AuthMode, AuthMode.Unknown> | 'deferred';
-export type ConnectCheckpoint = 'prerequisite_ok' | 'registered' | 'oauth_done' | 'cli_installed' | 'skill_installed' | 'authenticated' | 'cli_verified' | 'walkthrough_launched' | 'walkthrough_prompt_printed';
+export type ConnectCheckpoint = 'prerequisite_ok' | 'registered' | 'oauth_done' | 'cli_installed' | 'skill_installed' | 'plugin_installed' | 'authenticated' | 'cli_verified' | 'walkthrough_launched' | 'walkthrough_prompt_printed';
 export type CliFallbackOutcome = 'cli_verified' | 'cli_install_failed' | 'no_credentials' | 'invalid_credentials' | 'authentication_failed' | 'verification_failed' | 'abandoned';
 /** Ctrl+C killed a setup child — abandonment, not error. */
 export declare class ConnectInterruptedError extends Error {

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

@@ -0,0 +1,6 @@
+import { type InstallOptions } from './cli-install.js';
+export declare const HERMES_PLUGIN_SHA = "496cd63fefd982bbaa8a85ce78ef2270d700984f";
+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. */
+export declare function setHermesWebBackends(home: string): void;

package/dist/lib/hermes-plugin.js

@@ -0,0 +1,99 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import spawn from 'cross-spawn';
+import { capturedOutput, replay, SKILL_INSTALL_TIMEOUT_MS, STEP_MAX_BUFFER, } from './cli-install.js';
+import { commandNotFound, ConnectStepError, spawnStepError } from './connect-runtime.js';
+import { HARNESS_PROBE_TIMEOUT_MS } from './constants.js';
+import { errLine } from './output.js';
+// Bump per CLI release.
+export const HERMES_PLUGIN_SHA = '496cd63fefd982bbaa8a85ce78ef2270d700984f';
+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`;
+// Anchored to --ref: another rejected flag would fail the clone path too.
+const REF_UNSUPPORTED_PATTERN = /unrecognized arguments:[^\n]*--ref/;
+function installSpawnEnv(home, apiKey) {
+    // Hermes' install-time requires_env check reads os.environ, not our .env seed.
+    return { ...process.env, HERMES_HOME: home, TINYFISH_API_KEY: apiKey };
+}
+function runPluginInstall(source, env) {
+    // Captured even under --verbose: the fallback matches on stderr.
+    return spawn.sync('hermes', ['plugins', 'install', ...source, '--enable', '--force'], {
+        encoding: 'utf8',
+        maxBuffer: STEP_MAX_BUFFER,
+        timeout: SKILL_INSTALL_TIMEOUT_MS,
+        env,
+    });
+}
+function refUnsupported(result) {
+    return result.status !== 0 && REF_UNSUPPORTED_PATTERN.test(String(result.stderr ?? ''));
+}
+function runGit(args) {
+    const result = spawn.sync('git', args, {
+        encoding: 'utf8',
+        maxBuffer: STEP_MAX_BUFFER,
+        timeout: SKILL_INSTALL_TIMEOUT_MS,
+    });
+    if (!result.error && result.status === 0)
+        return;
+    if (commandNotFound(result.error)) {
+        throw new ConnectStepError('git is required to stage the pinned plugin; install git and run connect again', 'command_not_found');
+    }
+    // Built first: its interrupt check must run before any replay.
+    const error = spawnStepError('Could not stage the TinyFish Hermes plugin', result);
+    replay(capturedOutput(result));
+    throw error;
+}
+// Pre-`--ref` Hermes: stage the pin ourselves, mirroring `--ref` internals.
+function installFromClone(env) {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'tinyfish-hermes-plugin-'));
+    try {
+        runGit(['clone', '--depth', '1', PLUGIN_REPO_URL, tmp]);
+        runGit(['-C', tmp, 'fetch', '--depth', '1', 'origin', HERMES_PLUGIN_SHA]);
+        runGit(['-C', tmp, 'checkout', '--detach', HERMES_PLUGIN_SHA]);
+        return runPluginInstall([`${pathToFileURL(tmp).href}#hermes`], env);
+    }
+    finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+export function installHermesPlugin(home, apiKey, { verbose }) {
+    errLine('Installing the TinyFish web plugin in Hermes...');
+    const env = installSpawnEnv(home, apiKey);
+    // --ref always: a same-source reinstall without it keeps the previous pin.
+    const primary = runPluginInstall([PLUGIN_SOURCE, '--ref', HERMES_PLUGIN_SHA], env);
+    const result = refUnsupported(primary) ? installFromClone(env) : primary;
+    if (result.error || result.status !== 0) {
+        // A declined security scan exits 1 here, and reconnecting repeats it.
+        const error = spawnStepError(`Could not install the TinyFish web plugin in Hermes; to install it yourself run: ${HERMES_PLUGIN_MANUAL_INSTALL}`, result);
+        replay(capturedOutput(result));
+        throw error;
+    }
+    if (verbose)
+        replay(capturedOutput(result));
+}
+function hermesConfig(args, home) {
+    return spawn.sync('hermes', ['config', ...args], {
+        encoding: 'utf8',
+        maxBuffer: STEP_MAX_BUFFER,
+        timeout: HARNESS_PROBE_TIMEOUT_MS,
+        env: { ...process.env, HERMES_HOME: home },
+    });
+}
+function configWrite(home, args) {
+    const result = hermesConfig(args, home);
+    if (!result.error && result.status === 0)
+        return;
+    // Built first: its interrupt check must run before any replay.
+    const error = spawnStepError(`Could not run \`hermes config ${args.join(' ')}\``, result);
+    replay(capturedOutput(result));
+    throw error;
+}
+const HERMES_BACKEND_KEYS = ['web.search_backend', 'web.extract_backend'];
+/** After install only: backends must never name an absent provider. */
+export function setHermesWebBackends(home) {
+    for (const key of HERMES_BACKEND_KEYS)
+        configWrite(home, ['set', key, 'tinyfish']);
+}

package/package.json

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