@tiny-fish/cli 0.30.1-next.252 → 0.30.1-next.253

package/dist/commands/connect.d.ts

@@ -50,5 +50,5 @@ export declare function connectCursor(options: {
     attemptId?: string;
     verbose?: boolean;
 }): Promise<void>;
-export declare function launchAgent(client: AgentClient): void;
+export declare function launchAgent(client: AgentClient): Promise<void>;
 export declare function registerConnect(program: Command): void;

package/dist/commands/connect.js

@@ -204,7 +204,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 });
-        runPostInstallSteps(client, options, state, telemetry, signInDeferred);
+        await runPostInstallSteps(client, options, state, telemetry, signInDeferred);
     });
     return state.authMode;
 }
@@ -220,13 +220,13 @@ function connectedLine(client, signInDeferred) {
         `${RELOAD_ACTION[client.connectClient]} to pick up the tools.`);
 }
 // Runs after `completed` settled: steps fail alone, the rest still run.
-function runPostInstallSteps(client, options, state, telemetry, signInDeferred) {
+async function runPostInstallSteps(client, options, state, telemetry, signInDeferred) {
     let failed = false;
     // Modelled on upgrade's attempt(); interrupts rethrow and abandon remaining steps.
-    const attempt = (stage, run) => {
+    const attempt = async (stage, run) => {
         state.stage = stage;
         try {
-            run();
+            await run();
         }
         catch (error) {
             if (error instanceof ConnectInterruptedError)
@@ -237,17 +237,17 @@ function runPostInstallSteps(client, options, state, telemetry, signInDeferred)
     };
     try {
         if (options.cliInstall !== false) {
-            attempt("cli_install", () => runCliInstallStep(options, telemetry));
+            await attempt("cli_install", () => runCliInstallStep(options, telemetry));
         }
         if (client.skillAgent) {
-            attempt("skill_install", () => {
+            await attempt("skill_install", () => {
                 installWebSkill(client, { verbose: options.verbose ?? false });
                 telemetry.track("checkpoint", { phase: "skill_installed" });
             });
         }
         // Before auth: a failed sign-in must not lose the harness record.
         saveConnectContext(client.connectClient, telemetry.attemptId, state.authMode);
-        attempt("authentication", () => {
+        await attempt("authentication", () => {
             // A set timeout means headless; never shell an interactive login.
             ensureCliAuthenticated(client.connectClient, options.apiKey, {
                 interactiveLogin: options.authTimeoutMs === undefined,
@@ -262,11 +262,15 @@ function runPostInstallSteps(client, options, state, telemetry, signInDeferred)
                 errLine(connectedLine(client, signInDeferred));
         }
         else {
-            attempt("walkthrough_launch", () => {
+            await attempt("walkthrough_launch", async () => {
                 // Before the handover, or the only sign-in instructions scroll past under the agent.
                 if (signInDeferred && client.signInHint)
                     errLine(client.signInHint);
-                launchNativeMcpClient(client);
+                await launchNativeMcpClient(client, async (outcome) => {
+                    telemetry.track("checkpoint", { phase: walkthroughPhase(outcome) });
+                    // Flushed pre-block; the session-long handover would strand the delivery.
+                    await telemetry.flush();
+                });
             });
         }
     }
@@ -300,6 +304,9 @@ function runCliInstallStep(options, telemetry) {
     installTinyFishCli({ verbose: options.verbose ?? false, announce: true });
     telemetry.track("checkpoint", { phase: "cli_installed" });
 }
+function walkthroughPhase(outcome) {
+    return outcome === "printed" ? "walkthrough_prompt_printed" : "walkthrough_launched";
+}
 function finishSetupHint(connectClient) {
     return `Finish setup with: ${finishSetupCommand(connectClient)}`;
 }
@@ -392,7 +399,11 @@ export async function connectOpenClaw(options) {
         }
         state.stage = "walkthrough_launch";
         try {
-            launchOpenClawWalkthrough();
+            await launchOpenClawWalkthrough(async (outcome) => {
+                telemetry.track("checkpoint", { phase: walkthroughPhase(outcome) });
+                // Flushed pre-block; the session-long handover would strand the delivery.
+                await telemetry.flush();
+            });
         }
         catch (error) {
             trackPostInstallFailure("OpenClaw", state, telemetry, error);
@@ -511,8 +522,8 @@ const AGENT_LAUNCHERS = {
         throw new Error("Cursor has no launchable walkthrough. Open Cursor and start chatting.");
     },
 };
-export function launchAgent(client) {
-    AGENT_LAUNCHERS[client]();
+export async function launchAgent(client) {
+    await AGENT_LAUNCHERS[client]();
 }
 // A new client fails to compile until wired here.
 const CLIENT_CONNECTORS = {

package/dist/commands/onboard.js

@@ -187,7 +187,7 @@ async function runAgentSteps(interactive) {
     if (!launchId)
         return;
     try {
-        launchAgent(launchId);
+        await launchAgent(launchId);
     }
     catch (error) {
         errLine(`   Could not open ${agentLabel(launchId)}: ${errorMessage(error)}`);

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

@@ -45,7 +45,10 @@ export interface NativeMcpClient extends SupportedCommand {
         label: string;
     }[];
     addArgs: (mcpUrl: string, oauthResource: string) => string[];
+    /** Blocking terminal walkthrough; runs only behind the TTY gate. */
     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;
 }
@@ -80,5 +83,10 @@ export interface HarnessCapabilities {
 }
 /** Required booleans: a new harness or new flag fails to compile undecided. */
 export declare const HARNESS_CAPABILITIES: Record<Harness, HarnessCapabilities>;
-export declare function launchNativeMcpClient(client: NativeMcpClient): void;
-export declare function launchOpenClawWalkthrough(): void;
+/** "printed" = handed to the user to paste; the walkthrough was never started for them. */
+export type WalkthroughOutcome = "launched" | "printed";
+/** Awaited before the handover; track+flush must land pre-block. */
+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

@@ -1,5 +1,6 @@
 import spawn from "cross-spawn";
 import { SKILL_INSTALL_TIMEOUT_MS } from "./cli-install.js";
+import { detectHumanInitiated } from "./harness.js";
 import { harnessConfigPath } from "./harness-detect.js";
 import { errLine, sanitizeLine } from "./output.js";
 import { spawnStepError, } from "./connect-runtime.js";
@@ -74,9 +75,13 @@ export function openclawSkillUninstall() {
         timeoutMs: SKILL_INSTALL_TIMEOUT_MS,
     };
 }
-export const DEFAULT_ONBOARDING_PROMPT = "I just connected TinyFish. Call the guide_next_step tool now to begin. Then follow its " +
-    "instructions one step at a time. Ask for my input and wait for my reply before each subsequent " +
-    "TinyFish tool call.";
+export const DEFAULT_ONBOARDING_PROMPT = "I just connected TinyFish. Use the MCP server named `tinyfish` for every TinyFish tool call; " +
+    "if another TinyFish server is also registered, still use `tinyfish` and do not ask me which. " +
+    "Start by asking me what I want to look up on the web, and wait for my reply. Then call " +
+    "`guide_next_step` and follow its instructions one step at a time, asking for my input and " +
+    "waiting for my reply before each subsequent TinyFish tool call. If a tool call comes back " +
+    "blocked or not approved, tell me which tool needs approval and how to grant it, then wait for " +
+    "me instead of ending the walkthrough.";
 export const OPENCLAW_ONBOARDING_PROMPT = "I just installed the TinyFish skill. Guide me through it interactively: first ask what topic I " +
     "want to search and wait for my reply before using TinyFish Search. Show me the results, ask " +
     "which result I want to read, and wait before using TinyFish Fetch. Then ask what browser task " +
@@ -152,9 +157,12 @@ function launchCodexWalkthrough() {
     deepLink.searchParams.set("path", process.cwd());
     const result = openExternalUrl(deepLink.toString());
     if (result.error || result.status !== 0) {
-        throw spawnStepError("Could not open Codex", result);
+        // Headless box: nothing can open a window; recover like the gated clients.
+        printPromptForHandoff("Codex", "codex", DEFAULT_ONBOARDING_PROMPT, "Codex could not be opened here (no `codex://` handler)");
+        return "printed";
     }
     errLine("Codex opened with the TinyFish walkthrough ready. Send the prompt to start.");
+    return "launched";
 }
 export const CODEX = {
     command: "codex",
@@ -173,7 +181,7 @@ export const CODEX = {
         envVar: TINYFISH_API_KEY_VAR,
         addArgs: (mcpUrl) => [...urlAddArgs(mcpUrl), "--bearer-token-env-var", TINYFISH_API_KEY_VAR],
     },
-    launchWalkthrough: launchCodexWalkthrough,
+    detachedLaunch: launchCodexWalkthrough,
     // Retry only: running it after a finished inline OAuth is a second browser hop.
     loginArgs: ["mcp", "login", "tinyfish"],
     removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Codex" }],
@@ -350,15 +358,40 @@ export const HARNESS_CAPABILITIES = {
         authDeferredAtInstall: false,
     },
 };
-export function launchNativeMcpClient(client) {
-    errLine(`Starting the TinyFish walkthrough in ${client.displayName}...`);
-    if (client.launchWalkthrough) {
-        client.launchWalkthrough();
-        return;
+function printPromptForHandoff(displayName, command, prompt, reason) {
+    // "set up", not "connected": sign-in can still be deferred here.
+    errLine(`TinyFish is set up in ${displayName}.`);
+    errLine(`${reason}, so TinyFish did not launch it. Start ${displayName} (\`${command}\`) yourself ` +
+        `and paste this first message:`);
+    errLine("");
+    errLine(prompt);
+}
+/** One gate + one decide-before-block path for every terminal handover. */
+async function deliverWalkthrough(displayName, command, prompt, handover, onDecided) {
+    // Inherited-stdio handover: a non-TTY parent cannot approve tool calls.
+    if (!detectHumanInitiated()) {
+        await onDecided?.("printed");
+        printPromptForHandoff(displayName, command, prompt, `This terminal cannot answer ${displayName}'s tool-approval prompts`);
+        return "printed";
+    }
+    // Decided and delivered first: the handover blocks for the whole session.
+    await onDecided?.("launched");
+    errLine(`Starting the TinyFish walkthrough in ${displayName}...`);
+    handover();
+    return "launched";
+}
+export async function launchNativeMcpClient(client, onDecided) {
+    if (client.detachedLaunch) {
+        // Detached: the open attempt never blocks, so decide after it.
+        errLine(`Starting the TinyFish walkthrough in ${client.displayName}...`);
+        const outcome = client.detachedLaunch();
+        await onDecided?.(outcome);
+        return outcome;
     }
-    handOverTerminal(client.command, [DEFAULT_ONBOARDING_PROMPT], client.displayName);
+    return deliverWalkthrough(client.displayName, client.command, DEFAULT_ONBOARDING_PROMPT, () => client.launchWalkthrough
+        ? client.launchWalkthrough()
+        : handOverTerminal(client.command, [DEFAULT_ONBOARDING_PROMPT], client.displayName), onDecided);
 }
-export function launchOpenClawWalkthrough() {
-    errLine("Starting the TinyFish walkthrough in OpenClaw...");
-    handOverTerminal("openclaw", ["chat", "--message", OPENCLAW_ONBOARDING_PROMPT], "OpenClaw");
+export function launchOpenClawWalkthrough(onDecided) {
+    return deliverWalkthrough("OpenClaw", "openclaw", OPENCLAW_ONBOARDING_PROMPT, () => handOverTerminal("openclaw", ["chat", "--message", OPENCLAW_ONBOARDING_PROMPT], "OpenClaw"), onDecided);
 }

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

@@ -6,7 +6,7 @@ export type ConnectFailureStage = "prerequisite_check" | "registration_cleanup"
 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";
+export type ConnectCheckpoint = "prerequisite_ok" | "registered" | "oauth_done" | "cli_installed" | "skill_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/package.json

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