@tiny-fish/cli 0.39.1-next.311 → 0.40.0

package/dist/commands/connect.js

@@ -1,6 +1,6 @@
 import spawn from 'cross-spawn';
 import { CONNECT_SOURCE, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, validatedApiKey, } from '../lib/auth.js';
-import { CURSOR_SKILL_TARGET, OPENCLAW, openclawSkillInstallArgs, NATIVE_BY_HARNESS, launchNativeMcpClient, launchOmpWalkthrough, launchOpenClawWalkthrough, openExternalUrl, } from '../lib/connect-clients.js';
+import { CURSOR_SKILL_TARGET, OPENCLAW, openclawSkillInstallArgs, NATIVE_BY_HARNESS, launchNativeMcpClient, launchOmpWalkthrough, launchPiWalkthrough, launchOpenClawWalkthrough, openExternalUrl, } from '../lib/connect-clients.js';
 import { captureStdio, capturedOutput, installTinyFishCli, replay, SKILL_INSTALL_TIMEOUT_MS, STEP_MAX_BUFFER, } from '../lib/cli-install.js';
 import { ensureCliAuthenticated } from '../lib/connect-auth.js';
 import { createStdinPrompt, runCliFallback } from '../lib/connect-fallback.js';
@@ -9,6 +9,7 @@ import { ConnectInterruptedError, ConnectStepError, HoistedFailureReportedError,
 import { cursorInstallDeeplink, cursorMcpPath, readCursorTinyfishEntry, writeCursorMcpConfig, } from '../lib/cursor-config.js';
 import { runConnectAll } from '../lib/connect-all.js';
 import { ompMcpPath, readOmpTinyfishEntry, writeOmpMcpConfig } from '../lib/omp-config.js';
+import { PI_ADAPTER_INSTALL_COMMAND, piMcpAdapterState, piSkillDirMismatch, piMcpPath, readPiTinyfishEntry, writePiMcpConfig, } from '../lib/pi-config.js';
 import { ALL_HARNESSES, AuthMode, HARNESS_DISPLAY_NAMES, RELOAD_ACTION, } from '../lib/harness-detect.js';
 import { detectHumanInitiated } from '../lib/harness.js';
 import { TINYFISH_API_KEY_VAR } from '../lib/constants.js';
@@ -169,6 +170,22 @@ async function prepareInstallAuth(client, options, keyAuthSupported) {
     }
     return { keyedAdd, buildAddArgs };
 }
+/** Inherit for an inline-OAuth add; capture otherwise, piping prompts when seeded. */
+function addSpawnOptions(options, interactiveAdd, seeded) {
+    if (interactiveAdd)
+        return { stdio: 'inherit', timeout: options.authTimeoutMs };
+    if (!seeded)
+        return captureStdio(options.verbose ?? false);
+    return {
+        encoding: 'utf8',
+        // Without it, the 1 MiB default overflows into a misread Ctrl+C.
+        maxBuffer: STEP_MAX_BUFFER,
+        // The unattended path had no bound at all before; captureStdio's is the floor.
+        timeout: options.authTimeoutMs ?? SKILL_INSTALL_TIMEOUT_MS,
+        input: seeded.stdinInput,
+        env: seeded.env,
+    };
+}
 /** Returns the seeded-credential note when a key was written into a user-owned file. */
 function performMcpAdd(client, options, plan, attemptId) {
     const { keyedAdd, buildAddArgs } = plan;
@@ -183,20 +200,11 @@ function performMcpAdd(client, options, plan, attemptId) {
     const interactiveAdd = !(client.nonInteractiveAdd || keyedAdd);
     // After the removals: an interrupt there leaves no key behind.
     const seeded = keyedAdd?.spec.seedKey?.(keyedAdd.key);
-    const addOptions = interactiveAdd
-        ? { stdio: 'inherit', timeout: options.authTimeoutMs }
-        : seeded
-            ? {
-                encoding: 'utf8',
-                // Without it, the 1 MiB default overflows into a misread Ctrl+C.
-                maxBuffer: STEP_MAX_BUFFER,
-                // The unattended path had no bound at all before; captureStdio's is the floor.
-                timeout: options.authTimeoutMs ?? SKILL_INSTALL_TIMEOUT_MS,
-                input: seeded.stdinInput,
-                env: seeded.env,
-            }
-            : captureStdio(options.verbose ?? false);
-    const addResult = spawn.sync(client.command, addArgs, addOptions);
+    // Writing the entry ourselves skips the harness probe that saves it disabled.
+    if (seeded?.register(mcpUrl.toString())) {
+        return { note: seeded.note, seededHome: seeded.home };
+    }
+    const addResult = spawn.sync(client.command, addArgs, addSpawnOptions(options, interactiveAdd, seeded));
     // Rolls back first: signInStepError throws on a Ctrl+C.
     const failAdd = (build) => {
         seeded?.rollback();
@@ -214,7 +222,7 @@ function performMcpAdd(client, options, plan, attemptId) {
         // The tag keeps the path-bearing prose out of telemetry.
         { failureDetail: registration.tag }));
     }
-    return seeded?.note;
+    return { note: seeded?.note, seededHome: seeded?.home };
 }
 function performLoginStep(client, pendingLogin, options) {
     errLine('Signing in to TinyFish...');
@@ -289,7 +297,7 @@ async function connectNativeMcpClient(client, options) {
         // A probed client authenticates inside `mcp add` too, so a failure there is either.
         state.stage =
             loginArgs && !probeAuthenticated ? 'registration' : 'registration_or_authentication';
-        const seededNote = performMcpAdd(client, options, plan, telemetry.attemptId);
+        const { note: seededNote, seededHome } = performMcpAdd(client, options, plan, telemetry.attemptId);
         telemetry.track('checkpoint', { phase: 'registered' });
         const { authMode, signInDeferred } = completeAuthFlow(client, options, state, telemetry, {
             useKeyAuth,
@@ -301,7 +309,7 @@ async function connectNativeMcpClient(client, options) {
         state.authMode = authMode;
         // Registration/OAuth make MCP work; later steps are cosmetic and must not fail the attempt.
         settle(state, telemetry, 'completed', { authMode });
-        await runPostInstallSteps(client, options, state, telemetry, signInDeferred);
+        await runPostInstallSteps(client, options, state, telemetry, signInDeferred, seededHome);
     });
     return state.authMode;
 }
@@ -317,7 +325,7 @@ function connectedLine(client, signInDeferred) {
         `${RELOAD_ACTION[client.connectClient]} to pick up the tools.`);
 }
 // Runs after `completed` settled: steps fail alone, the rest still run.
-async function runPostInstallSteps(client, options, state, telemetry, signInDeferred) {
+async function runPostInstallSteps(client, options, state, telemetry, signInDeferred, seededHome) {
     let failed = false;
     // Modelled on upgrade's attempt(); interrupts rethrow and abandon remaining steps.
     const attempt = async (stage, run) => {
@@ -348,6 +356,7 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
                 extraPostInstall({
                     apiKey: validatedApiKey(options.apiKey),
                     verbose: options.verbose ?? false,
+                    seededHome,
                 });
                 telemetry.track('checkpoint', {
                     phase: 'plugin_installed',
@@ -501,6 +510,31 @@ export async function connectOpenClaw(options) {
         }
     });
 }
+const PI_RELOAD_COPY = 'TinyFish is configured in pi. Restart pi, then run `/mcp-auth tinyfish` there if it asks you ' +
+    'to sign in.';
+// The skill is the working path either way, so the note must not read as a failure.
+const PI_ADAPTER_DORMANT_NOTE = 'Note: pi has no built-in MCP support, so the entry in its mcp.json stays dormant until you ' +
+    `run \`${PI_ADAPTER_INSTALL_COMMAND}\`. The TinyFish skill works without it.`;
+// Only the dormant case was spoken for, leaving a working MCP install silent.
+const PI_ADAPTER_LIVE_NOTE = 'pi-mcp-adapter is installed, so pi loads the TinyFish MCP tools as well as the skill once ' +
+    'you restart it.';
+function piAdapterNote() {
+    const state = piMcpAdapterState();
+    if (state === 'installed')
+        return PI_ADAPTER_LIVE_NOTE;
+    return state === 'absent' ? PI_ADAPTER_DORMANT_NOTE : undefined;
+}
+// The `skills` CLI writes to the default dir even when pi reads another one.
+function piPostConnectNotes() {
+    const notes = [piAdapterNote()];
+    const skills = piSkillDirMismatch();
+    if (skills) {
+        notes.push(`Note: PI_CODING_AGENT_DIR points pi at ${skills.readFrom}, but the TinyFish skill ` +
+            `installed to ${skills.installedTo}. Copy or symlink it across for pi to load it.`);
+    }
+    const printable = notes.filter(Boolean);
+    return printable.length > 0 ? printable.join('\n') : undefined;
+}
 // Only interactive omp wires the OAuth handler; headless cannot sign in.
 const OMP_KEYLESS_COPY = 'TinyFish is configured in omp. Open omp and sign in to TinyFish when prompted, or run ' +
     '`/mcp reauth tinyfish` there.';
@@ -535,6 +569,22 @@ const CONFIG_FILE_HARNESSES = {
             reload: OMP_KEYLESS_COPY,
         },
     },
+    pi: {
+        skillTarget: { skillAgent: 'pi', displayName: HARNESS_DISPLAY_NAMES.pi },
+        registeredUrl: () => readPiTinyfishEntry().url,
+        write: writePiMcpConfig,
+        configPath: piMcpPath,
+        // No install deeplink exists; the copy carries the restart instead.
+        tryLaunch: () => false,
+        postConnectNote: piPostConnectNotes,
+        copy: {
+            verified: "TinyFish is connected and verified (health+auth). Restart pi and it's live.",
+            authFailed: (reason) => `TinyFish is configured, but the authenticated check failed (${reason}). ` +
+                'Fix: rotate/re-enter your key with `tinyfish auth login`, then re-run: tinyfish connect pi',
+            launched: PI_RELOAD_COPY,
+            reload: PI_RELOAD_COPY,
+        },
+    },
 };
 /** Writes the harness's MCP config file itself; no `mcp add` exists. */
 async function connectConfigFileHarness(harness, options) {
@@ -628,6 +678,9 @@ async function connectConfigFileHarness(harness, options) {
         else {
             errLine(spec.copy.reload);
         }
+        const note = spec.postConnectNote?.();
+        if (note)
+            errLine(note);
         settle(state, telemetry, 'completed', { authMode: resolvedKey ? AuthMode.ApiKey : 'deferred' });
     });
 }
@@ -643,6 +696,7 @@ function launchCursorDeeplink(mcpUrl) {
 /** Total over the non-native harnesses: a new one fails to compile until wired here. */
 const LAUNCH_OVERRIDES = {
     omp: launchOmpWalkthrough,
+    pi: launchPiWalkthrough,
     openclaw: launchOpenClawWalkthrough,
     // Cursor has no chat CLI to launch.
     cursor: () => {
@@ -683,6 +737,19 @@ const CONNECTOR_OVERRIDES = {
         }
         return undefined;
     },
+    pi: async (options) => {
+        await connectConfigFileHarness('pi', options);
+        if (options.launch) {
+            try {
+                await launchPiWalkthrough();
+            }
+            catch (error) {
+                errLine(error instanceof Error ? error.message : String(error));
+                errLine(finishSetupHint('pi'));
+            }
+        }
+        return undefined;
+    },
 };
 function requireNative(harness) {
     const client = NATIVE_BY_HARNESS.get(harness);

package/dist/commands/doctor.js

@@ -1,5 +1,5 @@
 import { CLI_VERSION } from '../lib/constants.js';
-import { checkAuthCall, checkCliVersion, checkConnectivity, checkCredential, checkHermesPlugin, checkRegistration, provesHarnessReach, verifyHarnessKey, } from '../lib/doctor-checks.js';
+import { checkAuthCall, checkCliVersion, checkConnectivity, checkCredential, checkHermesPlugin, checkPiAdapter, checkRegistration, provesHarnessReach, verifyHarnessKey, } from '../lib/doctor-checks.js';
 import { DOCTOR_COULD_NOT_RUN, DOCTOR_INVALID_INPUT, DOCTOR_SCHEMA_VERSION, doctorReportSchema, exitCodeFor, renderPretty, verdictFor, } from '../lib/doctor-report.js';
 import { applyRepairs, repairsFor } from '../lib/doctor-repairs.js';
 import { couldNotRunPayload, telemetryKey, telemetryPayload } from '../lib/doctor-telemetry.js';
@@ -30,11 +30,13 @@ export async function runDoctor(options) {
     ]);
     const hermesStatus = statuses.find((status) => status.harness === 'hermes');
     const hermesPlugin = hermesStatus ? checkHermesPlugin(hermesStatus) : undefined;
+    const piStatus = statuses.find((status) => status.harness === 'pi');
     const checks = [
         checkCliVersion(),
         connectivity,
         ...statuses.map((status, i) => checkRegistration(status, options.mcpUrl, keyAuths[i], !credential.key)),
         ...(hermesPlugin ? [hermesPlugin.check] : []),
+        ...(piStatus ? [checkPiAdapter(piStatus)] : []),
         credential.check,
         checkAuthCall(cliAuthResult),
     ];

package/dist/lib/connect-all-summary.js

@@ -9,7 +9,7 @@ const HIDDEN_ONCE_SOMETHING_WORKED = new Set([
 ]);
 /** A stale config dir is a detection signal with nothing behind it. */
 export function actionable(result) {
-    return result.detected && result.outcome !== 'stale_config';
+    return (result.detected && result.outcome !== 'stale_config' && result.outcome !== 'needs_first_run');
 }
 function absentSummaryLine(result, uninstall) {
     const name = DISPLAY_NAMES[result.harness];
@@ -29,6 +29,9 @@ function skippedSummaryLine(result) {
     if (result.outcome === 'stale_config') {
         return `… ${name} — config at ${result.configPath} but no \`${HARNESS_COMMANDS[result.harness]}\` on PATH, skipped. Install ${name}, then run: ${result.fixCommand}`;
     }
+    if (result.outcome === 'needs_first_run') {
+        return `… ${name} — installed but never run, so ${result.configPath} does not exist yet, skipped. Run \`${HARNESS_COMMANDS[result.harness]}\` once, then: ${result.fixCommand}`;
+    }
     if (result.outcome === 'not_reached') {
         return `… ${name} — not reached, the run stopped early. Fix: ${result.fixCommand}`;
     }

package/dist/lib/connect-all-uninstall.js

@@ -3,6 +3,7 @@ import { NATIVE_BY_HARNESS, openclawSkillUninstall } from './connect-clients.js'
 import { ConnectInterruptedError, spawnRemoval } from './connect-runtime.js';
 import { removeCursorMcpServer, planCursorWrite } from './cursor-config.js';
 import { planOmpWrite, removeOmpMcpServer } from './omp-config.js';
+import { piMcpPath, planPiWrite, removePiMcpServer } from './pi-config.js';
 import { HERMES_KEY_VAR, hermesEnvPath, removeHermesKey, resolveHermesHome } from './hermes-env.js';
 import { clearHermesWebBackends, HERMES_PLUGIN_SHA } from './hermes-plugin.js';
 import { HARNESS_DISPLAY_NAMES as DISPLAY_NAMES } from './harness-detect.js';
@@ -14,6 +15,8 @@ export function planText(harness, mcpUrl, apiKey) {
         return planCursorWrite(mcpUrl, apiKey);
     if (harness === 'omp')
         return planOmpWrite(mcpUrl, apiKey);
+    if (harness === 'pi')
+        return planPiWrite(mcpUrl, apiKey);
     // Only the keyed path seeds the .env; a keyless Hermes install writes nothing.
     if (harness === 'hermes' && apiKey) {
         return (`would run \`tinyfish connect hermes\` (harness-owned MCP write; the CLI writes ` +
@@ -29,6 +32,9 @@ export function uninstallPlanText(harness) {
     if (harness === 'omp') {
         return "would remove the tinyfish entry from omp's mcp.json (located via `omp config path`)";
     }
+    if (harness === 'pi') {
+        return `would remove the tinyfish entry from ${piMcpPath()}`;
+    }
     if (!uninstallRuns(harness)) {
         return `would print \`${uninstallPointer(harness)}\` (no removal command exists)`;
     }
@@ -62,7 +68,8 @@ function uninstallPointer(harness) {
 }
 /** `mcp remove` clears neither the key nor the backends we wrote. */
 function clearHermesLocalState() {
-    const home = resolveHermesHome();
+    const resolved = resolveHermesHome();
+    const home = typeof resolved === 'string' ? resolved : undefined;
     const advisories = [clearHermesEnvKey(home), clearHermesBackends(home)].filter((advisory) => advisory !== undefined);
     return advisories.length > 0 ? advisories.join(' ') : undefined;
 }
@@ -186,6 +193,10 @@ const MCP_JSON_UNINSTALLS = {
         remove: removeOmpMcpServer,
         fix: "Fix omp's mcp.json (at `omp config path`) by hand, then re-run: tinyfish connect --all --uninstall",
     },
+    pi: {
+        remove: removePiMcpServer,
+        fix: `Fix ${piMcpPath()} by hand, then re-run: tinyfish connect --all --uninstall`,
+    },
 };
 function uninstallMcpJson(detection, spec) {
     let result;

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

@@ -1,6 +1,6 @@
-import { type Harness } from './harness-detect.js';
+import { type Harness, type HarnessDetection } from './harness-detect.js';
 import { type VerifyDepth } from './verify.js';
-export type Outcome = 'not_detected' | 'not_installed' | 'stale_config' | 'installed' | 'failed' | 'harness_too_old' | 'interrupted' | 'auth_pending' | 'no_tty_auth_skip' | 'uninstalled' | 'uninstall_noop' | 'uninstall_pointer' | 'dry_run' | 'not_reached' | 'deselected';
+export type Outcome = 'not_detected' | 'not_installed' | 'stale_config' | 'needs_first_run' | 'installed' | 'failed' | 'harness_too_old' | 'interrupted' | 'auth_pending' | 'no_tty_auth_skip' | 'uninstalled' | 'uninstall_noop' | 'uninstall_pointer' | 'dry_run' | 'not_reached' | 'deselected';
 export type HarnessResultBase = {
     harness: Harness;
     detected: boolean;
@@ -34,5 +34,7 @@ export interface ConnectAllOptions {
     /** Setup-page id riding in on --url; joins "copied the command" to this run. */
     attemptId?: string;
 }
+/** The harness has never created its dir, so connecting would build one it does not own. */
+export declare function needsFirstRun(detection: HarnessDetection): boolean;
 export declare function runConnectAll(opts: ConnectAllOptions): Promise<number>;
 export declare const FIRST_TASK_PROMPT: string;

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 };
 }