@tiny-fish/cli 0.42.1 → 0.44.0

package/README.md

@@ -23,6 +23,14 @@ omp, OpenClaw, OpenCode) and opens a checklist with everything pre-selected. Pre
 them all, or use the arrow keys and space to narrow the set first; `q` cancels without touching
 anything. Terminals without raw-key support get a numbered prompt instead.
 
+Try Search without an account; run `tinyfish auth login` and reconnect to unlock all tools:
+
+```bash
+npx -y @tiny-fish/cli@latest connect opencode --launch
+npx -y @tiny-fish/cli@latest connect hermes --launch
+npx -y @tiny-fish/cli@latest connect omp --launch
+```
+
 Without a terminal (agents, CI), bare `connect` behaves exactly like `tinyfish connect --all`
 and says so on its first line: harnesses that can take your API key (via `TINYFISH_API_KEY` or
 `--api-key`) connect first, then the first harness that needs a browser sign-in opens your
@@ -85,17 +93,13 @@ the `use-tinyfish` skill this command installs for the other harnesses.
 
 ### Connect Hermes
 
-Add TinyFish MCP and the global `use-tinyfish` web skill, authenticate the CLI, and start the
-interactive walkthrough with one command:
+Add TinyFish MCP and the global `use-tinyfish` web skill, then start the interactive walkthrough:
 
 ```bash
-npx -y @tiny-fish/cli@latest connect hermes --launch --api-key sk-tinyfish-...
+npx -y @tiny-fish/cli@latest connect hermes --launch
 ```
 
-Hermes completes OAuth while adding the MCP server. `hermes mcp add` accepts no header flag, so
-`--api-key` cannot replace the Hermes sign-in — its only header path, `--auth header`, prompts
-interactively. After setup, the command starts the walkthrough in a Hermes session and leaves that
-session open for your replies.
+Without a key, Hermes gets Search. A key enables all tools without browser sign-in.
 
 ### Connect Command Code
 

package/dist/commands/auth.js

@@ -3,7 +3,7 @@ import * as readline from 'readline';
 import { Option } from 'commander';
 import { CONNECT_ATTEMPT_ENV, clearConfig, getDashboardUrl, loadConfig, maskKey, savePendingConnectAttempt, saveConfig, validateKeyFormat, } from '../lib/auth.js';
 import { TINYFISH_API_KEY_VAR } from '../lib/constants.js';
-import { err, errLine, out, outLine } from '../lib/output.js';
+import { err, errLine, out, outLine, warnLine } from '../lib/output.js';
 /**
  * Read a key from stdin without echoing it to the terminal.
  * Uses setRawMode on TTY so characters are never written to the screen.
@@ -74,6 +74,14 @@ function parkSeedAttempt() {
     if (seed)
         savePendingConnectAttempt(seed);
 }
+// Env var wins every later lookup; a silent save misleads.
+function warnIfEnvShadows(savedKey) {
+    const envKey = process.env[TINYFISH_API_KEY_VAR];
+    if (!envKey || envKey === savedKey)
+        return;
+    warnLine(`Warning: ${TINYFISH_API_KEY_VAR} is set in your environment and overrides the key just saved. ` +
+        `Unset it or update your shell profile, then check with 'tinyfish auth status'.`);
+}
 export function registerAuth(program) {
     const auth = program.command('auth').description('Manage your TinyFish API key');
     auth
@@ -120,6 +128,7 @@ export function registerAuth(program) {
         saveConfig(key);
         parkSeedAttempt();
         out({ status: 'ok', message: 'API key saved', key_preview: maskKey(key) });
+        warnIfEnvShadows(key);
     });
     auth
         .command('set')
@@ -141,6 +150,7 @@ export function registerAuth(program) {
         saveConfig(key);
         parkSeedAttempt();
         out({ status: 'ok', message: 'API key saved', key_preview: maskKey(key) });
+        warnIfEnvShadows(key);
     });
     auth
         .command('status')

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, launchPiWalkthrough, launchOpenClawWalkthrough, openExternalUrl, } from '../lib/connect-clients.js';
+import { CURSOR_SKILL_TARGET, KEYLESS_ONBOARDING_PROMPT, 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';
@@ -17,7 +17,7 @@ import { emitNotice } from '../lib/notice.js';
 import { SIGN_IN_PROBES } from '../lib/registration-detect.js';
 import { errLine, warnLine } from '../lib/output.js';
 import { z } from 'zod';
-import { verifyMcpAuth } from '../lib/verify.js';
+import { verifyMcpAuth, verifyMcpHealth } from '../lib/verify.js';
 import { gateApiKey } from '../lib/connect-preflight.js';
 import { apiBaseFromMcpUrl, DEFAULT_MCP_URL } from '../lib/mcp-endpoint.js';
 function removeExistingRegistration(client, removal, verbose) {
@@ -36,8 +36,8 @@ function exportApiKey(apiKey, displayName, deferOutro) {
         persistApiKeyToEnvironment(apiKey);
     }
     catch (error) {
-        errLine(`Could not export TINYFISH_API_KEY (${error instanceof Error ? error.message : String(error)}); ` +
-            'signing in instead.');
+        // Cause only: headless refuses below, so this must not promise a sign-in (PF-3803).
+        errLine(`Could not export TINYFISH_API_KEY (${error instanceof Error ? error.message : String(error)}).`);
         return false;
     }
     process.env[TINYFISH_API_KEY_VAR] = apiKey;
@@ -51,13 +51,15 @@ function exportApiKey(apiKey, displayName, deferOutro) {
     }
     return true;
 }
-/** Undefined leaves the client on its keyless path, if any. */
-function resolveKeyedAdd(client, storedKey, keyAuthSupported, deferOutro) {
+function resolveKeyedAdd(client, storedKey, keyAuthSupported, keyAuthOnly, deferOutro) {
     if (!storedKey || !keyAuthSupported || !client.keyAuth)
         return undefined;
     const keyed = { key: storedKey, spec: client.keyAuth };
     // Before the removals: a failed export must not strand the old registration.
     if (keyed.spec.envVar && !exportApiKey(keyed.key, client.displayName, deferOutro)) {
+        if (keyAuthOnly)
+            refuseFailedKeyExport(client);
+        errLine(`Signing in to ${client.displayName} instead.`);
         return undefined;
     }
     return keyed;
@@ -79,6 +81,12 @@ function refuseKeylessInstall(client, keyAuthSupported, headless = false) {
     throw new ConnectStepError(`Connecting ${client.displayName} needs a TinyFish API key, and ${noSignIn}. ` +
         `Run: tinyfish auth login, then ${rerun}`, 'invalid_config', { failureDetail: 'keyless_install_refused' });
 }
+/** Headless has no sign-in to degrade to, and the harness version is not the fault (PF-3803). */
+function refuseFailedKeyExport(client) {
+    // Never names a file: on Windows the write is `setx`, not a shell profile.
+    throw new ConnectStepError(`Could not save ${TINYFISH_API_KEY_VAR} to your environment, so ${client.displayName} has no ` +
+        `way to read your key. Fix that, then re-run: tinyfish connect ${client.connectClient}`, 'invalid_config', { failureDetail: 'key_export_failed' });
+}
 /** Resolved before the removals, so a refusal strands no registration. */
 function keylessAddArgs(client, keyAuthSupported) {
     if (!client.addArgs)
@@ -100,6 +108,11 @@ async function verifyKeyBeforeSeeding(apiKey, displayName, mcpUrl) {
     throw new ConnectStepError(`Your TinyFish API key was rejected (${verified.code ?? 'unknown'}), so it was not ` +
         `written to ${displayName}. Run: tinyfish auth login`, 'invalid_config', { failureDetail: `key_rejected status=${verified.status}` });
 }
+async function requireKeylessMcp(mcpUrl) {
+    if ((await verifyMcpHealth(mcpUrl, true)).ok)
+        return;
+    throw new ConnectStepError('TinyFish keyless Search is unavailable', 'invalid_config');
+}
 /** A bounded spawn's timeout means the sign-in never finished. */
 function signInStepError(message, result, bounded) {
     const error = spawnStepError(message, result);
@@ -157,18 +170,31 @@ async function runMissingHarnessFallback(displayName, connectClient, state, tele
 async function prepareInstallAuth(client, options, keyAuthSupported) {
     // Prod MCP accepts X-API-Key, so a stored key replaces the browser OAuth hop.
     const storedKey = validatedApiKey(options.apiKey);
-    const keyedAdd = resolveKeyedAdd(client, storedKey, keyAuthSupported, options.deferOutro);
-    // Refuses here when key-required; others keep their OAuth argv.
-    const buildAddArgs = keyedAdd
-        ? (mcpUrl) => keyedAdd.spec.addArgs(mcpUrl, keyedAdd.key)
-        : keylessAddArgs(client, keyAuthSupported);
+    const keyedAdd = resolveKeyedAdd(client, storedKey, keyAuthSupported, options.keyAuthOnly === true, options.deferOutro);
+    const keylessArgs = !storedKey ? client.keylessAddArgs : undefined;
+    const directInstall = !storedKey ? client.prepareKeylessInstall?.() : undefined;
+    let keyless = !!directInstall;
+    let buildAddArgs;
+    if (keyedAdd) {
+        buildAddArgs = (mcpUrl) => keyedAdd.spec.addArgs(mcpUrl, keyedAdd.key);
+    }
+    else if (keylessArgs && keyAuthSupported) {
+        buildAddArgs = keylessArgs;
+        keyless = true;
+    }
+    else if (keylessArgs && options.authTimeoutMs !== undefined) {
+        refuseKeylessInstall(client, false, true);
+    }
+    else if (!directInstall) {
+        buildAddArgs = keylessAddArgs(client, keyAuthSupported);
+    }
     if (options.keyAuthOnly && !keyedAdd)
         refuseKeylessInstall(client, keyAuthSupported, true);
     // Verify first: a revoked key in a foreign .env is unrecoverable.
     if (keyedAdd?.spec.seedKey) {
         await verifyKeyBeforeSeeding(keyedAdd.key, client.displayName, options.mcpUrl);
     }
-    return { keyedAdd, buildAddArgs };
+    return { keyedAdd, keyless, buildAddArgs, directInstall };
 }
 /** Inherit for an inline-OAuth add; capture otherwise, piping prompts when seeded. */
 function addSpawnOptions(options, interactiveAdd, seeded) {
@@ -186,14 +212,25 @@ function addSpawnOptions(options, interactiveAdd, seeded) {
         env: seeded.env,
     };
 }
+function performDirectInstall(client, install, mcpUrl) {
+    const registered = install.register(mcpUrl.toString());
+    if (registered.ok)
+        return { seededHome: install.home };
+    const detail = registered.detail ? `: ${registered.detail}` : '';
+    throw new ConnectStepError(`${client.displayName} reported success but TinyFish is not enabled there${detail}.`, 'invalid_config', { failureDetail: registered.tag });
+}
 /** 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;
+    const { keyedAdd, buildAddArgs, directInstall } = plan;
     const mcpUrl = new URL(options.mcpUrl);
     mcpUrl.searchParams.set('source', CONNECT_SOURCE);
     mcpUrl.searchParams.set('client', client.connectClient);
     mcpUrl.searchParams.set('connect_attempt_id', attemptId);
     errLine(`Adding TinyFish to ${client.displayName}...`);
+    if (directInstall)
+        return performDirectInstall(client, directInstall, mcpUrl);
+    if (!buildAddArgs)
+        throw new Error(`No MCP add arguments exist for ${client.displayName}`);
     // Header keys ride argv (/proc/<pid>/cmdline); these CLIs take headers no other way.
     const addArgs = buildAddArgs(mcpUrl.toString());
     // Capturing an inline-OAuth add hides the sign-in URL and hangs.
@@ -247,7 +284,11 @@ function announceAuthNotes(useKeyAuth, degradedNotes, seededNote) {
     }
 }
 function completeAuthFlow(client, options, state, telemetry, ctx) {
-    const { useKeyAuth, loginDegraded, loginArgs, probeAuthenticated } = ctx;
+    const { useKeyAuth, useKeyless, loginDegraded, loginArgs, probeAuthenticated } = ctx;
+    if (useKeyless) {
+        errLine('Using keyless TinyFish Search — no account or browser sign-in needed.');
+        return { authMode: AuthMode.Keyless, signInDeferred: false };
+    }
     // Codex runs OAuth inside `mcp add` and exits 0 either way, so the recorded state decides
     // whether the login step below still runs. Unknown keeps the pre-probe behaviour.
     const addSignedIn = probeAuthenticated?.();
@@ -287,6 +328,9 @@ async function connectNativeMcpClient(client, options) {
         state.harnessDegraded = !!client.loginArgs && !optionalSupported;
         const plan = await prepareInstallAuth(client, options, keyAuthSupported);
         const useKeyAuth = !!plan.keyedAdd;
+        const useKeyless = plan.keyless;
+        if (useKeyless)
+            await requireKeylessMcp(options.mcpUrl);
         telemetry.track('checkpoint', { phase: 'prerequisite_ok' });
         state.stage = 'registration_cleanup';
         for (const removal of client.removals)
@@ -301,13 +345,14 @@ async function connectNativeMcpClient(client, options) {
         telemetry.track('checkpoint', { phase: 'registered' });
         const { authMode, signInDeferred } = completeAuthFlow(client, options, state, telemetry, {
             useKeyAuth,
+            useKeyless,
             loginDegraded,
             loginArgs,
             probeAuthenticated,
             seededNote,
         });
         state.authMode = authMode;
-        // Registration/OAuth make MCP work; later steps are cosmetic and must not fail the attempt.
+        // Registration/OAuth make MCP work; the steps below must not fail the attempt.
         settle(state, telemetry, 'completed', { authMode });
         await runPostInstallSteps(client, options, state, telemetry, signInDeferred, seededHome);
     });
@@ -341,6 +386,8 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
         }
     };
     try {
+        // Above every step: a Ctrl+C below must not lose a registration already reported (PF-3803).
+        saveConnectContext(client.connectClient, telemetry.attemptId, state.authMode);
         if (options.cliInstall !== false) {
             await attempt('cli_install', () => runCliInstallStep(options, telemetry));
         }
@@ -350,10 +397,9 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
                 telemetry.track('checkpoint', { phase: 'skill_installed' });
             });
         }
-        const extraPostInstall = client.extraPostInstall;
-        if (extraPostInstall) {
+        if (client.extraPostInstall && state.authMode !== AuthMode.Keyless) {
             await attempt('plugin_install', () => {
-                extraPostInstall({
+                client.extraPostInstall?.({
                     apiKey: validatedApiKey(options.apiKey),
                     verbose: options.verbose ?? false,
                     seededHome,
@@ -364,15 +410,14 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
                 });
             });
         }
-        // Before auth: a failed sign-in must not lose the harness record.
-        saveConnectContext(client.connectClient, telemetry.attemptId, state.authMode);
-        await attempt('authentication', () => {
-            // A set timeout means headless; never shell an interactive login.
-            ensureCliAuthenticated(client.connectClient, options.apiKey, {
-                interactiveLogin: options.authTimeoutMs === undefined,
+        if (state.authMode !== AuthMode.Keyless) {
+            await attempt('authentication', () => {
+                ensureCliAuthenticated(client.connectClient, options.apiKey, {
+                    interactiveLogin: options.authTimeoutMs === undefined,
+                });
+                telemetry.track('checkpoint', { phase: 'authenticated' });
             });
-            telemetry.track('checkpoint', { phase: 'authenticated' });
-        });
+        }
         if (client.postConnectNote)
             errLine(client.postConnectNote);
         if (!options.launch) {
@@ -389,7 +434,7 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
                     telemetry.track('checkpoint', { phase: walkthroughPhase(outcome) });
                     // Flushed pre-block; the session-long handover would strand the delivery.
                     await telemetry.flush();
-                });
+                }, state.authMode === AuthMode.Keyless ? KEYLESS_ONBOARDING_PROMPT : undefined);
             });
         }
     }
@@ -655,18 +700,26 @@ async function connectConfigFileHarness(harness, options) {
     await runGuarded(state, telemetry, async () => {
         telemetry.track('started');
         telemetry.track('checkpoint', { phase: 'prerequisite_ok' });
-        // Auth first: a key lets the config carry an X-API-Key header, removing the sign-in hand-back.
-        state.stage = 'authentication';
-        // A set timeout means headless; never shell an interactive login.
-        ensureCliAuthenticated(harness, options.apiKey, {
-            interactiveLogin: options.authTimeoutMs === undefined,
-        });
-        telemetry.track('checkpoint', { phase: 'authenticated' });
-        const resolvedKey = validatedApiKey(options.apiKey);
-        // ensureCliAuthenticated leaves a key stored, and `auth status` exits 0 on a malformed one.
-        if (!resolvedKey) {
-            errLine('Ignoring the stored API key: invalid format. Run: tinyfish auth login');
-        }
+        const resolveAuth = async () => {
+            let resolvedKey = validatedApiKey(options.apiKey);
+            const keyless = !resolvedKey && harness === 'omp';
+            if (keyless) {
+                await requireKeylessMcp(options.mcpUrl);
+            }
+            else {
+                state.stage = 'authentication';
+                ensureCliAuthenticated(harness, options.apiKey, {
+                    interactiveLogin: options.authTimeoutMs === undefined,
+                });
+                resolvedKey = validatedApiKey(options.apiKey);
+                telemetry.track('checkpoint', { phase: 'authenticated' });
+                if (!resolvedKey) {
+                    errLine('Ignoring the stored API key: invalid format. Run: tinyfish auth login');
+                }
+            }
+            return { resolvedKey, keyless };
+        };
+        const { resolvedKey, keyless } = await resolveAuth();
         state.stage = 'registration';
         errLine(`Adding TinyFish to ${displayName}...`);
         const mcpUrl = new URL(options.mcpUrl);
@@ -686,12 +739,22 @@ async function connectConfigFileHarness(harness, options) {
             errLine('Repaired the existing TinyFish entry (updated auth/config to current).');
         }
         telemetry.track('checkpoint', { phase: 'registered' });
-        saveConnectContext(harness, telemetry.attemptId);
-        settle(state, telemetry, 'completed', { authMode: resolvedKey ? AuthMode.ApiKey : 'deferred' });
+        let authMode = keyless ? AuthMode.Keyless : 'deferred';
+        if (resolvedKey)
+            authMode = AuthMode.ApiKey;
+        state.authMode = authMode;
+        if (keyless)
+            saveConnectContext(harness, telemetry.attemptId, AuthMode.Keyless);
+        else
+            saveConnectContext(harness, telemetry.attemptId);
+        settle(state, telemetry, 'completed', { authMode });
         const postInstallFailed = installSkillPostSettle(spec, displayName, state, telemetry, options);
-        if (resolvedKey) {
+        if (keyless) {
+            errLine(`TinyFish keyless Search is connected in ${displayName}.`);
+        }
+        else if (resolvedKey) {
             // Deeplink would embed the key in a URL (process args, LaunchServices logs) — reload instead.
-            const verify = await verifyMcpAuth(resolvedKey);
+            const verify = await verifyMcpAuth(resolvedKey, apiBaseFromMcpUrl(options.mcpUrl));
             if (verify.ok) {
                 errLine(spec.copy.verified);
             }
@@ -710,6 +773,7 @@ async function connectConfigFileHarness(harness, options) {
             errLine(note);
         reportPostInstallFailure(harness, postInstallFailed, options.onPostInstallFailed);
     });
+    return state.authMode;
 }
 /** Writes mcp.json directly — no `cursor mcp add` exists. */
 export async function connectCursor(options) {
@@ -751,10 +815,10 @@ const CONNECTOR_OVERRIDES = {
         return undefined;
     },
     omp: async (options) => {
-        await connectConfigFileHarness('omp', options);
+        const authMode = await connectConfigFileHarness('omp', options);
         if (options.launch) {
             try {
-                await launchOmpWalkthrough();
+                await launchOmpWalkthrough(undefined, authMode === AuthMode.Keyless ? KEYLESS_ONBOARDING_PROMPT : undefined);
             }
             catch (error) {
                 // Post-settle, like the native walkthrough step: never fail the connect.
@@ -762,7 +826,7 @@ const CONNECTOR_OVERRIDES = {
                 errLine(finishSetupHint('omp'));
             }
         }
-        return undefined;
+        return authMode;
     },
     pi: async (options) => {
         await connectConfigFileHarness('pi', options);
@@ -839,6 +903,7 @@ async function connectSingleClient(client, options, mcpUrl, attemptId) {
         attemptId,
         // A key that the install cannot use leaves only a browser hop no agent can finish.
         keyAuthOnly: !detectHumanInitiated() && !!validatedApiKey(options.apiKey),
+        authTimeoutMs: detectHumanInitiated() ? undefined : 90_000,
         // Only here: a missing harness rescues via the CLI (PF-3707).
         fallbackWhenMissing: true,
         verbose: options.verbose ?? false,

package/dist/commands/doctor.js

@@ -22,7 +22,8 @@ function hermesPluginVersions(result) {
 export async function runDoctor(options) {
     const statuses = detectRegistrations(options.harness ? [options.harness] : undefined);
     const credential = checkCredential();
-    const cliAuth = credential.key ? verifyMcpAuth(credential.key) : undefined;
+    const apiBase = new URL(options.mcpUrl).origin;
+    const cliAuth = credential.key ? verifyMcpAuth(credential.key, apiBase) : undefined;
     const [connectivity, cliAuthResult, keyAuths] = await Promise.all([
         checkConnectivity(options.mcpUrl),
         cliAuth,

package/dist/commands/run.js

@@ -3,7 +3,7 @@ import { readFile } from 'node:fs/promises';
 import { z } from 'zod';
 import { getApiKey } from '../lib/auth.js';
 import { cancelRun, runAsync, runStream, runSync } from '../lib/client.js';
-import { err, errLine, handleApiError, out, outLine } from '../lib/output.js';
+import { err, errLine, handleApiError, out, outLine, warnLine } from '../lib/output.js';
 import { BASE_URL } from '../lib/constants.js';
 const VALID_BROWSER_PROFILES = ['lite', 'stealth'];
 const VALID_MODES = ['default', 'strict'];
@@ -257,7 +257,7 @@ async function runStreamPath(req, apiKey, pretty) {
     process.once('SIGINT', onSigint);
     let streamFailed = false;
     try {
-        for await (const event of runStream(req, apiKey, controller.signal)) {
+        for await (const event of runStream(req, apiKey, controller.signal, warnDroppedEvents)) {
             if (!handleStreamEvent(event, pretty, (id) => {
                 capturedRunId = id;
             })) {
@@ -292,6 +292,9 @@ async function runStreamPath(req, apiKey, pretty) {
     if (streamFailed)
         process.exit(1);
 }
+function warnDroppedEvents(count) {
+    warnLine(`Warning: skipped ${count} malformed stream event${count === 1 ? '' : 's'}; output may be incomplete.`);
+}
 export function registerRun(agentCmd) {
     const runCmd = agentCmd
         .command('run')

package/dist/lib/auth.d.ts

@@ -4,8 +4,9 @@ export declare function configFile(): string;
 /** Install channel baked onto connect context; the connect flow is always CLI-driven. */
 export declare const CONNECT_SOURCE = "tinyfish_cli";
 export declare const CONNECT_ATTEMPT_ENV = "TINYFISH_CONNECT_ATTEMPT_ID";
+export declare const RUNTIME_ATTEMPT_ENV = "TINYFISH_RUNTIME_ATTEMPT_ID";
 /** Mirrors ConnectAuthMode; duplicated to keep auth.ts free of connect-runtime imports. */
-export type RecordedAuthMode = 'api-key' | 'oauth' | 'deferred';
+export type RecordedAuthMode = 'api-key' | 'keyless' | 'oauth' | 'deferred';
 interface ConnectEntry {
     attempt_id: string;
     auth_mode?: RecordedAuthMode;

package/dist/lib/auth.js

@@ -19,7 +19,9 @@ export const CONNECT_SOURCE = 'tinyfish_cli';
 // An env var, not a flag: released CLIs ignore an unknown one, and the installer's PATH
 // prepend means a copied command can still run a CLI far older than the page that wrote it.
 export const CONNECT_ATTEMPT_ENV = 'TINYFISH_CONNECT_ATTEMPT_ID';
-const RECORDED_AUTH_MODES = ['api-key', 'oauth', 'deferred'];
+// Per-request; distinct from CONNECT_ATTEMPT_ENV (install seed, consumed once).
+export const RUNTIME_ATTEMPT_ENV = 'TINYFISH_RUNTIME_ATTEMPT_ID';
+const RECORDED_AUTH_MODES = ['api-key', 'keyless', 'oauth', 'deferred'];
 export function loadConfig() {
     try {
         const raw = JSON.parse(fs.readFileSync(configFile(), 'utf8'));

package/dist/lib/client.d.ts

@@ -4,10 +4,11 @@ type ConnectMap = Record<string, {
     attempt_id: string;
 }> | undefined;
 export declare function buildConnectHeaders(connect: ConnectMap, caller: string | null): Record<string, string>;
+export declare function setupPageConnectHeaders(attemptId: string | undefined): Record<string, string>;
 export declare function resolveClientName(env?: Record<string, string | undefined>): string;
 export declare function runSync(req: CliAgentRunParams, apiKey: string): Promise<AgentRunResponse>;
 export declare function runAsync(req: CliAgentRunParams, apiKey: string): Promise<AgentRunAsyncResponse>;
-export declare function runStream(req: CliAgentRunParams, apiKey: string, signal?: AbortSignal): AsyncGenerator<AgentRunWithStreamingResponse>;
+export declare function runStream(req: CliAgentRunParams, apiKey: string, signal?: AbortSignal, onDropped?: (count: number) => void): AsyncGenerator<AgentRunWithStreamingResponse>;
 export declare function listRuns(opts: RunListParams, apiKey: string, timeout?: number, baseUrl?: string): Promise<RunListResponse>;
 export declare function getRun(runId: string, apiKey: string): Promise<Run>;
 export declare function getRunSteps(runId: string, apiKey: string): Promise<RunStepsResponse>;

package/dist/lib/client.js

@@ -1,5 +1,5 @@
 import { APIStatusError, agentRunAsyncResponseSchema, agentRunResponseSchema, agentRunWithStreamingResponseSchema, browserSessionSchema, searchQueryResponseSchema, TinyFish, runSchema, runStatusSchema, } from '@tiny-fish/sdk';
-import { CONNECT_SOURCE, loadConfig } from './auth.js';
+import { CONNECT_SOURCE, RUNTIME_ATTEMPT_ENV, loadConfig } from './auth.js';
 import { API_URL_OVERRIDE, CLI_AGENT_IDENTITY, CLI_VERSION } from './constants.js';
 import { detectHarness, detectHumanInitiated } from './harness.js';
 import { captureNotice } from './notice.js';
@@ -29,6 +29,15 @@ function connectHeadersFor(client, attemptId) {
         'X-TF-Connect-Attempt-Id': attemptId,
     };
 }
+export function setupPageConnectHeaders(attemptId) {
+    if (!attemptId || !z.uuid().safeParse(attemptId).success)
+        return {};
+    return {
+        'X-TF-Connect-Source': 'setup_page',
+        'X-TF-Connect-Client': 'cli',
+        'X-TF-Connect-Attempt-Id': attemptId,
+    };
+}
 // Forwarded explicitly: the pinned published SDK may predate TF_CLIENT_* support.
 // Non-printable chars make fetch throw; 128 is the server cap (client_name varchar(128)).
 const sanitize = (value) => (value ?? '')
@@ -63,7 +72,12 @@ class TinyFishCliClient extends TinyFish {
         // Reuse the already-resolved client_name so connect_client can never diverge from it
         // (same sanitize + precedence, not a second raw read of TF_CLIENT_NAME).
         const connectCaller = clientName || null;
-        for (const [key, value] of Object.entries(buildConnectHeaders(loadConfig().connect, connectCaller))) {
+        // Snippet env (per call) overrides stored install connect context.
+        const connectHeaders = {
+            ...buildConnectHeaders(loadConfig().connect, connectCaller),
+            ...setupPageConnectHeaders(process.env[RUNTIME_ATTEMPT_ENV]),
+        };
+        for (const [key, value] of Object.entries(connectHeaders)) {
             const clean = sanitize(value);
             if (clean)
                 headers[key] = clean;
@@ -82,14 +96,20 @@ class TinyFishCliClient extends TinyFish {
         captureNotice(response.headers);
         if (!response.ok) {
             let message = response.statusText;
+            let code;
             try {
                 const body = (await response.json());
-                message = body?.error?.message ?? body?.message ?? message;
+                if (typeof body?.error?.message === 'string')
+                    message = body.error.message;
+                else if (typeof body?.message === 'string')
+                    message = body.message;
+                if (typeof body?.error?.code === 'string')
+                    code = body.error.code;
             }
             catch {
                 // Non-JSON body — keep statusText
             }
-            throw new ApiError(response.status, message);
+            throw new ApiError(response.status, message, code);
         }
         if (response.status === 204)
             return undefined;
@@ -113,7 +133,7 @@ function sdk(apiKey, call) {
 }
 function rethrowSdkError(error) {
     if (error instanceof APIStatusError) {
-        throw new ApiError(error.statusCode, error.message);
+        throw new ApiError(error.statusCode, error.message, error.code);
     }
     if (error instanceof Error) {
         throw error;
@@ -180,7 +200,14 @@ function normalizeStreamEvent(event) {
         error: typeof data['error'] === 'object' && data['error'] !== null ? data['error'] : null,
     };
 }
-async function* parseSseStream(stream) {
+function isCompleteShaped(event) {
+    return (typeof event === 'object' && event !== null && event.type === 'COMPLETE');
+}
+function malformedCompleteMessage(event, lastRunId) {
+    const runId = typeof event['run_id'] === 'string' ? event['run_id'] : lastRunId;
+    return `Stream sent a COMPLETE event the CLI could not parse; run state unknown. Check it with \`tinyfish agent run get ${runId ?? '<run-id>'}\`.`;
+}
+async function* parseSseStream(stream, onUnparseableLine) {
     const reader = stream.getReader();
     let buffer = '';
     const parseLine = (rawLine) => {
@@ -191,6 +218,7 @@ async function* parseSseStream(stream) {
             return JSON.parse(line.slice('data:'.length).trim());
         }
         catch {
+            onUnparseableLine();
             return undefined;
         }
     };
@@ -232,23 +260,36 @@ export function runAsync(req, apiKey) {
         return parseWithSchema(agentRunAsyncResponseSchema, response, 'Invalid async run response');
     });
 }
-export async function* runStream(req, apiKey, signal) {
+export async function* runStream(req, apiKey, signal, onDropped) {
     let stream = null;
+    let droppedEvents = 0;
+    let lastRunId = null;
     try {
         stream = await createSdkClient(apiKey).postStream('/v1/automation/run-sse', {
             json: req,
             signal,
         });
-        for await (const event of parseSseStream(stream)) {
+        for await (const event of parseSseStream(stream, () => (droppedEvents += 1))) {
             const parsed = agentRunWithStreamingResponseSchema.safeParse(normalizeStreamEvent(event));
-            if (parsed.success)
+            if (parsed.success) {
+                if ('run_id' in parsed.data)
+                    lastRunId = parsed.data.run_id;
                 yield parsed.data;
+                continue;
+            }
+            // A dropped COMPLETE means the run never visibly terminates.
+            if (isCompleteShaped(event))
+                throw new Error(malformedCompleteMessage(event, lastRunId));
+            droppedEvents += 1;
         }
     }
     catch (error) {
         rethrowSdkError(error);
     }
     finally {
+        // Runs on caller break too, so the count still surfaces.
+        if (droppedEvents > 0)
+            onDropped?.(droppedEvents);
         if (stream) {
             try {
                 await stream.cancel();

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

@@ -98,6 +98,9 @@ export function mapConnectError(base, e, oauthBudget, spentBrowserSlot, fixComma
     };
 }
 export async function authGate(base, oauthBudget, fixCommand, ctx) {
+    if (!ctx.keyed && harnessSpec(base.harness).keylessFallback) {
+        return { headlessAuth: !ctx.isTTY, spentBrowserSlot: false };
+    }
     if (!ctx.isTTY && !ctx.keyed) {
         return headlessGate(base, oauthBudget, fixCommand);
     }

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

@@ -17,12 +17,14 @@ export function planText(harness, mcpUrl, apiKey) {
         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 ` +
             `${HERMES_KEY_VAR} to Hermes' .env, installs the tinyfish plugin at ` +
             `${HERMES_PLUGIN_SHA.slice(0, 12)}, and points its web backends at tinyfish)`);
     }
+    if (harness === 'hermes') {
+        return 'would run `tinyfish connect hermes` (writes a keyless MCP header; no credential or plugin write)';
+    }
     return `would run \`tinyfish connect ${harness}\` (harness-owned MCP write; no local file touched by the CLI)`;
 }
 export function uninstallPlanText(harness) {