@tiny-fish/cli 0.39.1-next.311 → 0.40.1-next.317

package/dist/lib/connect-all.js

@@ -127,13 +127,19 @@ function noWorkOutcome(d, uninstall) {
         return 'not_detected';
     if (!uninstall && isStaleConfig(d))
         return 'stale_config';
+    if (!uninstall && needsFirstRun(d))
+        return 'needs_first_run';
     return undefined;
 }
+/** The harness has never created its dir, so connecting would build one it does not own. */
+export function needsFirstRun(detection) {
+    return detection.detected && !detection.configDirExists;
+}
 /** A config-writing connect needs no binary; every other harness spawns one. */
 function isStaleConfig(detection) {
     const spec = harnessSpec(detection.harness);
-    // Cursor's IDE reads mcp.json binary-less; omp's path needs the binary.
-    const binaryless = spec.cliWritesConfig && !spec.configPathFromBinary;
+    // Cursor's IDE reads mcp.json binary-less; omp and pi have no second reader.
+    const binaryless = spec.cliWritesConfig && spec.readableWithoutBinary;
     return detection.detected && !detection.binaryOnPath && !binaryless;
 }
 async function resolvePick(detections, opts, prompt) {
@@ -141,7 +147,7 @@ async function resolvePick(detections, opts, prompt) {
     let mode = 'all';
     // Before willAttempt/cliNeeded: a cursor-only pick must not hoist the CLI.
     // A stale config dir has no binary to connect, so never offer it as a choice.
-    const offerable = detections.filter((d) => d.detected && !isStaleConfig(d));
+    const offerable = detections.filter((d) => d.detected && !isStaleConfig(d) && !needsFirstRun(d));
     if (opts.pick && offerable.length > 0) {
         const connected = new Set(Object.keys(loadConfig().connect ?? {}));
         const pick = await pickHarnesses(offerable, connected, { prompt });
@@ -236,13 +242,14 @@ async function connectLoop(detections, opts, deselected, io) {
         if (results.some((r) => r.harness === detection.harness))
             continue;
         const { harness, detected, configPath } = detection;
-        const staleConfig = isStaleConfig(detection);
+        // One source of truth with `stepped`, or a skipped harness lands on the wrong row.
+        const noWork = noWorkOutcome(detection, opts.uninstall);
         results.push({
             harness,
             detected,
             configPath,
             installed: false,
-            outcome: staleConfig ? 'stale_config' : detected ? 'not_reached' : 'not_detected',
+            outcome: noWork ?? 'not_reached',
             fixCommand: `tinyfish connect ${detection.harness}`,
         });
     }
@@ -389,6 +396,7 @@ const LAUNCHERS = [
     { harness: 'cursor', args: [FIRST_TASK_PROMPT] },
     { harness: 'claude-code', args: [FIRST_TASK_PROMPT] },
     { harness: 'omp', args: [FIRST_TASK_PROMPT] },
+    { harness: 'pi', args: [FIRST_TASK_PROMPT] },
 ];
 async function launchFirstTask(results) {
     const candidates = LAUNCHERS.filter((l) => results.some((r) => r.harness === l.harness && r.installed) &&

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

@@ -19,6 +19,8 @@ export declare const CURSOR_SKILL_TARGET: {
 };
 /** The harness reads the key from its own store. */
 interface SeededInstall {
+    /** Reused by the plugin step, so a second probe cannot disagree. */
+    home: string;
     /** Pins the add child at the home the key landed in. */
     env: typeof process.env;
     /** Answers prompts `mcp add` still asks once the key is seeded. */
@@ -27,6 +29,8 @@ interface SeededInstall {
     note: string;
     /** Undoes the seed, carrying the value it replaced. */
     rollback: () => void;
+    /** Writes the entry ourselves; false falls back to the harness command. */
+    register: (mcpUrl: string) => boolean;
     /** `mcp add` exits 0 even having saved nothing; the code lies. */
     confirmRegistered: () => {
         ok: boolean;
@@ -57,6 +61,7 @@ interface BaseMcpClient extends SupportedCommand, Pick<HarnessSpec, 'skillAgent'
     extraPostInstall?: (options: {
         apiKey?: string;
         verbose: boolean;
+        seededHome?: string;
     }) => void;
     /** Pin `extraPostInstall` installs, reported on the plugin_installed checkpoint. */
     pluginVersion?: string;
@@ -86,7 +91,7 @@ export type NativeMcpClient = OauthCapableMcpClient | KeyRequiredMcpClient;
  * quotes back out. Untested on Windows.
  */
 export declare function openExternalUrl(url: string): ReturnType<typeof spawn.sync>;
-/** `mcp add` exits 0 after saving nothing, or a disabled entry. */
+/** Writes exit 0 having saved nothing, a disabled entry, or a keyless one. */
 export declare function hermesRegistrationEnabled(home: string): {
     ok: boolean;
     detail?: string;
@@ -94,7 +99,7 @@ export declare function hermesRegistrationEnabled(home: string): {
 };
 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" | "omp" | "grok" | "cursor" | "codex" | "hermes" | "opencode" | "claude-code", NativeMcpClient>;
+export declare const NATIVE_BY_HARNESS: Map<"openclaw" | "omp" | "grok" | "cursor" | "codex" | "hermes" | "opencode" | "pi" | "claude-code", NativeMcpClient>;
 export declare const OPENCLAW: SupportedCommand;
 /** "printed" = handed to the user to paste; the walkthrough was never started for them. */
 export type WalkthroughOutcome = 'launched' | 'printed';
@@ -102,4 +107,5 @@ 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 launchOmpWalkthrough(onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;
+export declare function launchPiWalkthrough(onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;
 export declare function launchOpenClawWalkthrough(onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;

package/dist/lib/connect-clients.js

@@ -3,12 +3,12 @@ import { SKILL_INSTALL_TIMEOUT_MS } from './cli-install.js';
 import { detectHumanInitiated } from './harness.js';
 import { harnessConfigPath } from './harness-detect.js';
 import { errLine, sanitizeLine, warnLine } from './output.js';
-import { ConnectStepError, spawnStepError, } from './connect-runtime.js';
+import { ConnectInterruptedError, ConnectStepError, spawnStepError, } from './connect-runtime.js';
 import { TINYFISH_API_KEY_VAR } from './constants.js';
 import { 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_VERSION, installHermesPlugin, setHermesWebBackends, } from './hermes-plugin.js';
+import { HERMES_PLUGIN_VERSION, installHermesPlugin, removeHermesMcpEntry, setHermesWebBackends, writeHermesMcpEntry, } from './hermes-plugin.js';
 const HERMES_SEED_TIMEOUT_MS = 120_000;
 const OPENCLAW_SKILL = '@tinyfish/tinyfish';
 // --force makes this an unconditional overwrite, so the same call installs and refreshes.
@@ -100,11 +100,19 @@ function launchHermesWalkthrough() {
     }
     handOverTerminal('hermes', ['--resume', sessionId], 'Hermes');
 }
-/** `mcp add` exits 0 after saving nothing, or a disabled entry. */
+/** Writes exit 0 having saved nothing, a disabled entry, or a keyless one. */
 export function hermesRegistrationEnabled(home) {
     const entry = readHermesEntry(home);
-    if (entry.state === 'enabled')
-        return { ok: true };
+    if (entry.state === 'enabled') {
+        if (entry.usesKeyHeader)
+            return { ok: true };
+        // Exit codes carry no signal, so a corrupt entry can only be caught here.
+        return {
+            ok: false,
+            detail: 'the entry does not read the seeded key',
+            tag: 'hermes_entry_no_key_header',
+        };
+    }
     // Each of these is a different repair, so none of them share wording.
     const detail = {
         disabled: 'the entry was saved disabled',
@@ -117,28 +125,47 @@ export function hermesRegistrationEnabled(home) {
 }
 // A plain Error settles unexpected_error; cli_connect_stage is load-bearing.
 function requireHermesHome() {
-    const home = resolveHermesHome();
-    if (!home) {
-        throw new ConnectStepError("Could not determine Hermes' home directory from `hermes dump`", 'invalid_config', { failureDetail: 'hermes_home_undetermined' });
+    const resolved = resolveHermesHome();
+    if (typeof resolved === 'string')
+        return resolved;
+    throw new ConnectStepError("Could not determine Hermes' home directory from `hermes dump`", 'invalid_config', { failureDetail: `hermes_home_undetermined_${resolved.reason}` });
+}
+/** Our own write, so `mcp add`'s install-time probe never disables the entry. */
+function registerHermesEntry(home, mcpUrl) {
+    try {
+        writeHermesMcpEntry(home, mcpUrl);
+    }
+    catch (error) {
+        // A Ctrl+C must abandon the attempt, not fall through to `mcp add`.
+        if (error instanceof ConnectInterruptedError)
+            throw error;
+        return false;
     }
-    return home;
+    return hermesRegistrationEnabled(home).ok;
 }
 function seedHermesKey(apiKey) {
     const home = requireHermesHome();
     const restore = captureHermesKeyRestore(home);
     writeHermesKey(home, apiKey);
+    // Set before the write, which can land even when it later throws.
+    let wroteEntry = false;
     return {
+        home,
         // Pins HERMES_HOME so a sticky profile can't shadow this key.
         env: { ...process.env, HERMES_HOME: home },
         // Three: a failed `mcp remove` adds an extra Overwrite prompt.
         stdinInput: 'y\ny\ny\n',
         note: `Wrote ${HERMES_KEY_VAR} to ${hermesEnvPath(home)} — Hermes reads the key from there.`,
-        rollback: () => rollbackHermesKey(home, restore),
+        rollback: () => rollbackHermesKey(home, restore, wroteEntry),
+        register: (mcpUrl) => {
+            wroteEntry = true;
+            return registerHermesEntry(home, mcpUrl);
+        },
         confirmRegistered: () => hermesRegistrationEnabled(home),
     };
 }
 // A failed re-run must not cost a working key.
-function rollbackHermesKey(home, restore) {
+function rollbackHermesKey(home, restore, wroteEntry) {
     try {
         // The next `hermes mcp add` silently reuses whatever value survives here.
         restore();
@@ -146,13 +173,23 @@ function rollbackHermesKey(home, restore) {
     catch {
         warnLine(`Could not restore ${HERMES_KEY_VAR} in ${hermesEnvPath(home)}; check it by hand.`);
     }
+    if (!wroteEntry)
+        return;
+    try {
+        // Left behind, the row stays enabled with no key behind it.
+        removeHermesMcpEntry(home);
+    }
+    catch {
+        warnLine(`Could not remove the tinyfish entry in ${hermesConfigPath(home)}; check it by hand.`);
+    }
 }
 // Hermes is keyRequired; a missing key here is a resolution bug.
-function installHermesWebPlugin({ apiKey, verbose }) {
+function installHermesWebPlugin({ apiKey, verbose, seededHome, }) {
     if (!apiKey) {
         throw new ConnectStepError('No TinyFish API key was available to install the Hermes web plugin', 'invalid_config');
     }
-    const home = requireHermesHome();
+    // Reuses the seed's home: a second `hermes dump` can disagree with the first.
+    const home = seededHome ?? requireHermesHome();
     installHermesPlugin(home, apiKey, { verbose });
     setHermesWebBackends(home);
 }
@@ -295,6 +332,9 @@ export async function launchNativeMcpClient(client, onDecided) {
 export function launchOmpWalkthrough(onDecided) {
     return deliverWalkthrough('omp', 'omp', DEFAULT_ONBOARDING_PROMPT, () => handOverTerminal('omp', [DEFAULT_ONBOARDING_PROMPT], 'omp'), onDecided);
 }
+export function launchPiWalkthrough(onDecided) {
+    return deliverWalkthrough('Pi', 'pi', DEFAULT_ONBOARDING_PROMPT, () => handOverTerminal('pi', [DEFAULT_ONBOARDING_PROMPT], 'Pi'), onDecided);
+}
 export function launchOpenClawWalkthrough(onDecided) {
     return deliverWalkthrough('OpenClaw', 'openclaw', OPENCLAW_ONBOARDING_PROMPT, () => handOverTerminal('openclaw', ['chat', '--message', OPENCLAW_ONBOARDING_PROMPT], 'OpenClaw'), onDecided);
 }

package/dist/lib/doctor-checks.d.ts

@@ -11,6 +11,7 @@ export declare function checkCredential(): {
 };
 export declare function checkAuthCall(auth: VerifyResult | undefined): DoctorCheck;
 export declare function verifyHarnessKey(status: RegistrationStatus, cliAuth: Promise<VerifyResult> | undefined, mcpUrl: string): Promise<VerifyResult> | undefined;
+export declare function checkPiAdapter(status: RegistrationStatus): DoctorCheck;
 export interface HermesPluginResult {
     check: DoctorCheck;
     observedVersion?: string;

package/dist/lib/doctor-checks.js

@@ -4,6 +4,7 @@ import { AuthMode, Registered } from './harness-detect.js';
 import { resolveHermesHome } from './hermes-env.js';
 import { hermesWebBackendsOurs, readHermesPluginStatus, } from './hermes-plugin.js';
 import { endpointOf, isDefaultEndpoint } from './mcp-endpoint.js';
+import { PI_ADAPTER_INSTALL_COMMAND, piMcpAdapterState } from './pi-config.js';
 import { boundedVersion } from './output.js';
 import { verifyMcpHealth } from './verify.js';
 // A green auth mode with a red auth call proves nothing, so the call's verdict gates the claim.
@@ -250,6 +251,40 @@ function hermesPluginVerdict(home) {
         observedVersion: boundedVersion(probe.status.plugin_version ?? ''),
     };
 }
+// Warn, not fail: the TinyFish skill works in pi with no adapter, so nothing is broken.
+export function checkPiAdapter(status) {
+    const base = {
+        id: 'pi-adapter',
+        title: 'Pi MCP adapter',
+        harness: 'pi',
+        scope: 'harness',
+    };
+    if (!status.detected)
+        return { ...base, status: 'skip', detail: 'harness not installed' };
+    if (status.registered !== Registered.Yes) {
+        const why = status.registered === Registered.Unknown
+            ? 'pi registration could not be determined'
+            : 'TinyFish is not registered in pi';
+        return { ...base, status: 'skip', detail: why };
+    }
+    const state = piMcpAdapterState();
+    if (state === 'installed') {
+        return { ...base, status: 'pass', detail: 'installed, so pi reads the tinyfish MCP entry' };
+    }
+    if (state === 'unknown') {
+        return {
+            ...base,
+            status: 'warn',
+            detail: "could not read pi's settings.json, so whether the adapter is installed is unknown",
+        };
+    }
+    return {
+        ...base,
+        status: 'warn',
+        detail: 'not installed, so the tinyfish MCP entry is dormant (the TinyFish skill works without it). ' +
+            `Fix: ${PI_ADAPTER_INSTALL_COMMAND}`,
+    };
+}
 export function checkHermesPlugin(status) {
     const base = {
         id: 'hermes-plugin',
@@ -263,12 +298,12 @@ export function checkHermesPlugin(status) {
     if (status.registered !== Registered.Yes) {
         return { check: { ...base, status: 'skip', detail: 'TinyFish is not registered in Hermes' } };
     }
-    const home = resolveHermesHome();
-    if (!home) {
+    const resolved = resolveHermesHome();
+    if (typeof resolved !== 'string') {
         return {
             check: { ...base, status: 'warn', detail: "could not determine Hermes' home directory" },
         };
     }
-    const { observedVersion, ...verdict } = hermesPluginVerdict(home);
+    const { observedVersion, ...verdict } = hermesPluginVerdict(resolved);
     return { check: { ...base, ...verdict }, observedVersion };
 }

package/dist/lib/doctor-report.d.ts

@@ -31,6 +31,7 @@ declare const doctorCheckSchema: z.ZodObject<{
         codex: "codex";
         hermes: "hermes";
         opencode: "opencode";
+        pi: "pi";
         "claude-code": "claude-code";
     }>>;
     scope: z.ZodEnum<{
@@ -48,6 +49,7 @@ declare const doctorHarnessSchema: z.ZodObject<{
         codex: "codex";
         hermes: "hermes";
         opencode: "opencode";
+        pi: "pi";
         "claude-code": "claude-code";
     }>;
     detected: z.ZodBoolean;
@@ -74,6 +76,7 @@ declare const doctorRepairSchema: z.ZodObject<{
         codex: "codex";
         hermes: "hermes";
         opencode: "opencode";
+        pi: "pi";
         "claude-code": "claude-code";
     }>>;
     command: z.ZodString;
@@ -102,6 +105,7 @@ export declare const doctorReportSchema: z.ZodObject<{
             codex: "codex";
             hermes: "hermes";
             opencode: "opencode";
+            pi: "pi";
             "claude-code": "claude-code";
         }>>;
         scope: z.ZodEnum<{
@@ -119,6 +123,7 @@ export declare const doctorReportSchema: z.ZodObject<{
             codex: "codex";
             hermes: "hermes";
             opencode: "opencode";
+            pi: "pi";
             "claude-code": "claude-code";
         }>;
         detected: z.ZodBoolean;
@@ -145,6 +150,7 @@ export declare const doctorReportSchema: z.ZodObject<{
             codex: "codex";
             hermes: "hermes";
             opencode: "opencode";
+            pi: "pi";
             "claude-code": "claude-code";
         }>>;
         command: z.ZodString;

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

@@ -23,5 +23,7 @@ export interface HarnessDetection {
     configPath: string;
     /** False with `detected` true means a stale config dir: nothing to run. */
     binaryOnPath: boolean;
+    /** True with no config dir means installed but never launched. */
+    configDirExists: boolean;
 }
 export declare function detectInstalledHarnesses(): HarnessDetection[];

package/dist/lib/harness-detect.js

@@ -3,6 +3,7 @@ import * as os from 'os';
 import * as path from 'path';
 import which from 'which';
 import { ALL_HARNESSES, harnessSpec } from './harness-spec.js';
+import { piAgentDir, piBinaryIsPi } from './pi-config.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]));
@@ -31,13 +32,18 @@ export function commandOnPath(command) {
         return false;
     }
 }
+// PI_CODING_AGENT_DIR moves pi's dir; a guessed path would be written unread.
+const CONFIG_PATH_RESOLVERS = { pi: piAgentDir };
 export function harnessConfigPath(harness) {
-    return path.join(os.homedir(), harnessSpec(harness).configDir); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
+    const resolved = CONFIG_PATH_RESOLVERS[harness]?.();
+    return resolved ?? 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 spec. */
 export function harnessDisplayPath(harness) {
     return `~/${harnessSpec(harness).configDir}`;
 }
+// `pi` is a two-letter name an unrelated npm package also claims; confirm before trusting it.
+const BINARY_VERIFIERS = { pi: piBinaryIsPi };
 export function detectInstalledHarnesses() {
     return ALL_HARNESSES.map((harness) => {
         const configPath = harnessConfigPath(harness);
@@ -48,13 +54,15 @@ export function detectInstalledHarnesses() {
         catch {
             configDirExists = false;
         }
-        // Config dir means ran once; PATH means runnable now.
-        const binaryOnPath = commandOnPath(HARNESS_COMMANDS[harness]);
+        // Config dir means ran once; a verified binary means runnable now.
+        const onPath = commandOnPath(HARNESS_COMMANDS[harness]);
+        const binaryOnPath = onPath && (BINARY_VERIFIERS[harness]?.() ?? true);
         return {
             harness,
             detected: configDirExists || binaryOnPath,
             configPath,
             binaryOnPath,
+            configDirExists,
         };
     });
 }

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

@@ -1,5 +1,5 @@
 /** The `skills` CLI's own agent names, not ours. */
-export type SkillAgent = 'claude-code' | 'codex' | 'cursor' | 'hermes-agent' | 'opencode';
+export type SkillAgent = 'claude-code' | 'codex' | 'cursor' | 'hermes-agent' | 'opencode' | 'pi';
 export interface HarnessSupportCheck {
     args: string[];
     /** Missing → nothing can work; setup fails. */
@@ -74,8 +74,8 @@ export interface HarnessSpec {
     keyHeldByCli?: true;
     /** Connect writes the MCP config file; no harness binary is spawned. */
     cliWritesConfig?: true;
-    /** Binary resolves the config path; absent binary, nothing reads it. */
-    configPathFromBinary?: true;
+    /** A second reader (Cursor's IDE) loads the config with no harness binary on PATH. */
+    readableWithoutBinary?: true;
     /** `mcp add` succeeds unauthenticated; OAuth lands at first tool use. */
     authDeferredAtInstall?: true;
 }
@@ -139,6 +139,7 @@ export declare const HARNESS_SPECS: {
         configDir: string;
         reloadAction: string;
         skillAgent: "cursor";
+        readableWithoutBinary: true;
         canVerifyAuth: true;
         keyHeldByCli: true;
         cliWritesConfig: true;
@@ -192,7 +193,6 @@ export declare const HARNESS_SPECS: {
         displayName: string;
         configDir: string;
         reloadAction: string;
-        configPathFromBinary: true;
         canVerifyAuth: true;
         keyHeldByCli: true;
         cliWritesConfig: true;
@@ -236,6 +236,16 @@ export declare const HARNESS_SPECS: {
         removals: never[];
         postConnectNote: string;
     };
+    pi: {
+        command: string;
+        displayName: string;
+        configDir: string;
+        reloadAction: string;
+        skillAgent: "pi";
+        canVerifyAuth: true;
+        keyHeldByCli: true;
+        cliWritesConfig: true;
+    };
 };
 /** Derived from spec keys; one entry extends every union. */
 export type Harness = keyof typeof HARNESS_SPECS;
@@ -246,4 +256,4 @@ export type NonNativeHarness = {
     [K in Harness]: 'urlStyle' extends keyof (typeof HARNESS_SPECS)[K] ? never : K;
 }[Harness];
 /** Native MCP harnesses carry add-generation fields; the rest override connect. */
-export declare const NATIVE_HARNESSES: ("openclaw" | "omp" | "grok" | "cursor" | "codex" | "hermes" | "opencode" | "claude-code")[];
+export declare const NATIVE_HARNESSES: ("openclaw" | "omp" | "grok" | "cursor" | "codex" | "hermes" | "opencode" | "pi" | "claude-code")[];

package/dist/lib/harness-spec.js

@@ -114,6 +114,7 @@ export const HARNESS_SPECS = {
         configDir: '.cursor',
         reloadAction: 'reload the window',
         skillAgent: 'cursor',
+        readableWithoutBinary: true,
         canVerifyAuth: true,
         keyHeldByCli: true,
         cliWritesConfig: true,
@@ -167,7 +168,6 @@ export const HARNESS_SPECS = {
         displayName: 'omp',
         configDir: '.omp',
         reloadAction: 'restart it',
-        configPathFromBinary: true,
         canVerifyAuth: true,
         keyHeldByCli: true,
         cliWritesConfig: true,
@@ -213,6 +213,16 @@ export const HARNESS_SPECS = {
         removals: [],
         postConnectNote: OPENCODE_MODEL_NOTE,
     },
+    pi: {
+        command: 'pi',
+        displayName: 'Pi',
+        configDir: '.pi/agent',
+        reloadAction: 'restart it',
+        skillAgent: 'pi',
+        canVerifyAuth: true,
+        keyHeldByCli: true,
+        cliWritesConfig: true,
+    },
 };
 export const ALL_HARNESSES = Object.keys(HARNESS_SPECS);
 export function harnessSpec(harness) {

package/dist/lib/harness.js

@@ -28,6 +28,8 @@ const HARNESS_FINGERPRINTS = [
     { name: 'hermes', matches: (env) => hasVarWithPrefix(env, 'HERMES_') },
     // Exact key, not a prefix: opencode writes OPENCODE=1 at startup, reads every OPENCODE_* as config.
     { name: 'opencode', matches: (env) => Boolean(env['OPENCODE']) },
+    // Observed: pi launched from Claude Code inherits CLAUDECODE=1.
+    { name: 'pi', matches: (env) => env['PI_CODING_AGENT'] === 'true' },
     {
         name: 'claude-code',
         matches: (env) => env['CLAUDECODE'] === '1' || Boolean(env['CLAUDE_CODE_ENTRYPOINT']),

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

@@ -1,5 +1,8 @@
 /** Every message about the entry names this path. */
 export declare function hermesConfigPath(home: string): string;
+export declare const HERMES_HEADER_TEMPLATE = "Bearer ${MCP_TINYFISH_API_KEY}";
+/** Both the writer and the gate key on this, so they cannot disagree. */
+export declare const HERMES_MCP_SERVER_KEY = "tinyfish";
 /** Callers branch on these; each is a different repair. */
 export type HermesEntry = {
     state: 'unreadable';

package/dist/lib/hermes-config.js

@@ -8,7 +8,9 @@ export function hermesConfigPath(home) {
     return path.join(home, 'config.yaml');
 }
 // Hermes persists the key as an interpolation template (mcp_config.py:174-182).
-const HEADER_TEMPLATE = `Bearer \${${HERMES_KEY_VAR}}`;
+export const HERMES_HEADER_TEMPLATE = `Bearer \${${HERMES_KEY_VAR}}`;
+/** Both the writer and the gate key on this, so they cannot disagree. */
+export const HERMES_MCP_SERVER_KEY = 'tinyfish';
 // Foreign file: model only what we read, tolerate the rest.
 const entrySchema = z.looseObject({
     // Anything goes: the runtime defaults unrecognised values to enabled.
@@ -16,7 +18,9 @@ const entrySchema = z.looseObject({
     headers: z.record(z.string(), z.unknown()).optional(),
 });
 const configSchema = z
-    .looseObject({ mcp_servers: z.looseObject({ tinyfish: entrySchema.nullish() }).nullish() })
+    .looseObject({
+    mcp_servers: z.looseObject({ [HERMES_MCP_SERVER_KEY]: entrySchema.nullish() }).nullish(),
+})
     .nullish();
 const TRUTHY_STRINGS = new Set(['true', '1', 'yes', 'on']);
 const FALSY_STRINGS = new Set(['false', '0', 'no', 'off']);
@@ -42,7 +46,7 @@ function isEnabled(value) {
 /** Only the header template proves this entry uses the seeded key. */
 function hasKeyHeader(headers) {
     const authorization = Object.entries(headers ?? {}).find(([name]) => name.toLowerCase() === 'authorization');
-    return authorization?.[1] === HEADER_TEMPLATE;
+    return authorization?.[1] === HERMES_HEADER_TEMPLATE;
 }
 /** Connect's gate and doctor's probe share this, so they cannot disagree. */
 export function readHermesEntry(home) {
@@ -60,7 +64,7 @@ export function readHermesEntry(home) {
     catch {
         return { state: 'unparseable' };
     }
-    const entry = config?.mcp_servers?.tinyfish;
+    const entry = config?.mcp_servers?.[HERMES_MCP_SERVER_KEY];
     if (!entry)
         return { state: 'absent' };
     const usesKeyHeader = hasKeyHeader(entry.headers);

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

@@ -1,5 +1,11 @@
+/** Each reason is a different repair, so telemetry keeps them apart. */
+export type HermesHomeReason = 'timeout' | 'exit' | 'no_line' | 'relative';
+/** Failure carries why, so connect tags it without a second probe. */
+export interface HermesHomeFailure {
+    reason: HermesHomeReason;
+}
 /** Asking Hermes beats reimplementing its profile override, which we'd drift from. */
-export declare function resolveHermesHome(): string | undefined;
+export declare function resolveHermesHome(): string | HermesHomeFailure;
 export declare const HERMES_KEY_VAR = "MCP_TINYFISH_API_KEY";
 /** Named in every message about the seeded key, so no caller rebuilds the path. */
 export declare function hermesEnvPath(home: string): string;

package/dist/lib/hermes-env.js

@@ -14,13 +14,16 @@ export function resolveHermesHome() {
         env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
         timeout: HARNESS_PROBE_TIMEOUT_MS,
     });
+    if (result.error?.code === 'ETIMEDOUT') {
+        return { reason: 'timeout' };
+    }
     if (result.error || result.status !== 0)
-        return undefined;
+        return { reason: 'exit' };
     const raw = HERMES_HOME_LINE.exec(sanitizeLine(`${result.stdout ?? ''}\n${result.stderr ?? ''}`))?.[1];
     if (!raw)
-        return undefined;
+        return { reason: 'no_line' };
     const expanded = raw === '~' || raw.startsWith('~/') ? path.join(os.homedir(), raw.slice(2)) : raw;
-    return path.isAbsolute(expanded) ? expanded : undefined;
+    return path.isAbsolute(expanded) ? expanded : { reason: 'relative' };
 }
 export const HERMES_KEY_VAR = 'MCP_TINYFISH_API_KEY';
 /** Named in every message about the seeded key, so no caller rebuilds the path. */

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

@@ -4,6 +4,10 @@ export declare const HERMES_PLUGIN_SHA = "496cd63fefd982bbaa8a85ce78ef2270d70098
 export declare const HERMES_PLUGIN_VERSION = "0.1.0";
 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;
+/** Absent `enabled` reads as enabled, so never write this field-by-field. */
+export declare function writeHermesMcpEntry(home: string, mcpUrl: string): void;
+/** Retracts our row; an absent `enabled` reads as enabled, so a partial one is live. */
+export declare function removeHermesMcpEntry(home: string): void;
 /** After install only: backends must never name an absent provider. */
 export declare function setHermesWebBackends(home: string): void;
 /** Ours-only unsets: a user-chosen backend value survives the uninstall. */

package/dist/lib/hermes-plugin.js

@@ -7,6 +7,7 @@ import { z } from 'zod';
 import { capturedOutput, replay, SKILL_INSTALL_TIMEOUT_MS, STEP_MAX_BUFFER, } from './cli-install.js';
 import { commandNotFound, ConnectStepError, spawnStepError, throwIfInterrupted, } from './connect-runtime.js';
 import { HARNESS_PROBE_TIMEOUT_MS } from './constants.js';
+import { HERMES_HEADER_TEMPLATE, HERMES_MCP_SERVER_KEY } from './hermes-config.js';
 import { errLine, parseJson } from './output.js';
 // Bump per CLI release.
 export const HERMES_PLUGIN_SHA = '496cd63fefd982bbaa8a85ce78ef2270d700984f';
@@ -95,6 +96,21 @@ function configWrite(home, args) {
     replay(capturedOutput(result));
     throw error;
 }
+/** Absent `enabled` reads as enabled, so never write this field-by-field. */
+export function writeHermesMcpEntry(home, mcpUrl) {
+    const entry = {
+        url: mcpUrl,
+        headers: { Authorization: HERMES_HEADER_TEMPLATE },
+        enabled: true,
+    };
+    const result = hermesConfig(['set', `mcp_servers.${HERMES_MCP_SERVER_KEY}`, JSON.stringify(entry)], home);
+    // `config set` exits 0 on a bad key, so only an interrupt is worth raising here.
+    throwIfInterrupted(result);
+}
+/** Retracts our row; an absent `enabled` reads as enabled, so a partial one is live. */
+export function removeHermesMcpEntry(home) {
+    configWrite(home, ['unset', `mcp_servers.${HERMES_MCP_SERVER_KEY}`]);
+}
 const HERMES_BACKEND_KEYS = ['web.search_backend', 'web.extract_backend'];
 // Dispatch falls back to web.backend, and the plugin's own setup can set it.
 const HERMES_OWNED_BACKEND_KEYS = [...HERMES_BACKEND_KEYS, 'web.backend'];