@tiny-fish/cli 0.42.1 → 0.44.0

package/dist/lib/connect-all.js

@@ -8,10 +8,11 @@ import { authGate, mapConnectError, OAUTH_SIGN_IN_TIMEOUT_MS } from './connect-a
 import { actionable, computeExitCode, reloadHint, renderSummary } from './connect-all-summary.js';
 import { planText, uninstallHarness, uninstallPlanText } from './connect-all-uninstall.js';
 import { createStdinPrompt, runCliFallback } from './connect-fallback.js';
+import { KEYLESS_ONBOARDING_PROMPT } from './connect-clients.js';
 import { gateApiKey } from './connect-preflight.js';
 import { ConnectInterruptedError } from './connect-runtime.js';
 import { pickHarnesses } from './connect-picker.js';
-import { commandOnPath, detectInstalledHarnesses, HARNESS_COMMANDS, HARNESS_DISPLAY_NAMES as DISPLAY_NAMES, ALL_HARNESSES, } from './harness-detect.js';
+import { commandOnPath, detectInstalledHarnesses, AuthMode, HARNESS_COMMANDS, HARNESS_DISPLAY_NAMES as DISPLAY_NAMES, ALL_HARNESSES, } from './harness-detect.js';
 import { detectHumanInitiated } from './harness.js';
 import { emitNotice } from './notice.js';
 import { errLine, outLine, setErrIndent } from './output.js';
@@ -44,7 +45,7 @@ async function verifyHarness(harness, mcpUrl, keyed, apiKey) {
         return health;
     if (!apiKey)
         return { depth: 'health+auth', ok: false, reason: 'no stored API key' };
-    return verifyMcpAuth(apiKey);
+    return verifyMcpAuth(apiKey, new URL(mcpUrl).origin);
 }
 /** The non-connect settlements: undetected, stale, dry-run, uninstall. */
 function settleWithoutConnect(detection, opts, base) {
@@ -109,7 +110,9 @@ async function processHarness(detection, opts, prompt, oauthBudget, hoistedCliIn
     }
     // The probe, not the flag, decides: a harness that degraded to OAuth is not key-authed.
     const keyAuthed = authMode ? authMode === 'api-key' : keyed;
-    const verify = await verifyHarness(harness, opts.mcpUrl, keyAuthed, apiKey);
+    const verify = authMode === AuthMode.Keyless
+        ? { depth: 'health', ok: true }
+        : await verifyHarness(harness, opts.mcpUrl, keyAuthed, apiKey);
     return {
         ...base,
         installed: true,
@@ -426,6 +429,9 @@ async function launchFirstTask(results) {
     if (!chosen)
         return false;
     outLine(`Starting ${DISPLAY_NAMES[chosen.harness]} with your first TinyFish task...`);
-    const result = spawn.sync(HARNESS_COMMANDS[chosen.harness], chosen.args, { stdio: 'inherit' });
+    const keyless = chosen.harness === 'omp' &&
+        results.some((result) => result.harness === 'omp' && !result.keyAuthed);
+    const args = keyless ? [KEYLESS_ONBOARDING_PROMPT] : chosen.args;
+    const result = spawn.sync(HARNESS_COMMANDS[chosen.harness], args, { stdio: 'inherit' });
     return !result.error;
 }

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

@@ -11,6 +11,7 @@ export declare function openclawSkillUninstall(): {
 };
 export declare const DEFAULT_ONBOARDING_PROMPT: string;
 export declare const OPENCLAW_ONBOARDING_PROMPT: string;
+export declare const KEYLESS_ONBOARDING_PROMPT: string;
 export type { SkillAgent };
 /** Cursor writes its own MCP config, so it has no descriptor to carry this. */
 export declare const CURSOR_SKILL_TARGET: {
@@ -48,15 +49,17 @@ interface BaseMcpClient extends SupportedCommand, Pick<HarnessSpec, 'skillAgent'
         /** Writes into the harness's store, so connect verifies the key first. */
         seedKey?: (apiKey: string) => SeededInstall;
     };
+    keylessAddArgs?: (mcpUrl: string) => string[];
+    prepareKeylessInstall?: () => DirectInstall;
     loginArgs?: string[];
     removals: {
         args: string[];
         label: string;
     }[];
     /** Blocking terminal walkthrough; runs only behind the TTY gate. */
-    launchWalkthrough?: () => void;
+    launchWalkthrough?: (prompt: string) => void;
     /** Own window, never inherits stdio; reports its own outcome. */
-    detachedLaunch?: () => WalkthroughOutcome;
+    detachedLaunch?: (prompt: string) => WalkthroughOutcome;
     /** Post-install like the skill step: failures warn, never fail the attempt. */
     extraPostInstall?: (options: {
         apiKey?: string;
@@ -85,6 +88,10 @@ interface KeyRequiredMcpClient extends BaseMcpClient {
     loginArgs?: never;
 }
 export type NativeMcpClient = OauthCapableMcpClient | KeyRequiredMcpClient;
+export interface DirectInstall {
+    home?: string;
+    register: (mcpUrl: string) => ReturnType<typeof hermesRegistrationEnabled>;
+}
 /**
  * `cmd` re-parses its command line after `/c`, so an unquoted `&` in the query string ends the
  * command and truncates the URL. Quoting needs windowsVerbatimArguments, or Node escapes the
@@ -92,7 +99,7 @@ export type NativeMcpClient = OauthCapableMcpClient | KeyRequiredMcpClient;
  */
 export declare function openExternalUrl(url: string): ReturnType<typeof spawn.sync>;
 /** Writes exit 0 having saved nothing, a disabled entry, or a keyless one. */
-export declare function hermesRegistrationEnabled(home: string): {
+export declare function hermesRegistrationEnabled(home: string, mode?: 'api-key' | 'keyless', expectedUrl?: string): {
     ok: boolean;
     detail?: string;
     tag?: string;
@@ -105,7 +112,7 @@ export declare const OPENCLAW: SupportedCommand;
 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 launchOmpWalkthrough(onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;
+export declare function launchNativeMcpClient(client: NativeMcpClient, onDecided?: OnWalkthroughDecided, prompt?: string): Promise<WalkthroughOutcome>;
+export declare function launchOmpWalkthrough(onDecided?: OnWalkthroughDecided, prompt?: string): Promise<WalkthroughOutcome>;
 export declare function launchPiWalkthrough(onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;
 export declare function launchOpenClawWalkthrough(onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;

package/dist/lib/connect-clients.js

@@ -4,7 +4,7 @@ import { detectHumanInitiated } from './harness.js';
 import { harnessConfigPath } from './harness-detect.js';
 import { errLine, sanitizeLine, warnLine } from './output.js';
 import { ConnectInterruptedError, ConnectStepError, spawnStepError, } from './connect-runtime.js';
-import { TINYFISH_API_KEY_VAR } from './constants.js';
+import { TINYFISH_ACCESS_MODE_HEADER, TINYFISH_API_KEY_VAR, TINYFISH_KEYLESS_ACCESS_MODE, } 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';
@@ -44,6 +44,8 @@ export const OPENCLAW_ONBOARDING_PROMPT = 'I just installed the TinyFish skill.
     '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 ' +
     'I want to complete and wait before using TinyFish Agent. Never skip ahead or choose for me.';
+export const KEYLESS_ONBOARDING_PROMPT = 'I just connected TinyFish Search. Ask what I want to look up and wait for my reply. Then search ' +
+    'with the `tinyfish` MCP server, show results, and explain signing up unlocks TinyFish Fetch and Agent.';
 /** Cursor writes its own MCP config, so it has no descriptor to carry this. */
 export const CURSOR_SKILL_TARGET = {
     skillAgent: HARNESS_SPECS.cursor.skillAgent,
@@ -65,14 +67,14 @@ export function openExternalUrl(url) {
     }
     return spawn.sync('xdg-open', [url], { stdio: 'ignore' });
 }
-function launchCodexWalkthrough() {
+function launchCodexWalkthrough(prompt) {
     const deepLink = new URL('codex://new');
-    deepLink.searchParams.set('prompt', DEFAULT_ONBOARDING_PROMPT);
+    deepLink.searchParams.set('prompt', prompt);
     deepLink.searchParams.set('path', process.cwd());
     const result = openExternalUrl(deepLink.toString());
     if (result.error || result.status !== 0) {
         // 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)');
+        printPromptForHandoff('Codex', 'codex', 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.');
@@ -85,8 +87,8 @@ function handOverTerminal(command, args, displayName) {
         throw spawnStepError(`Could not launch ${displayName}`, result);
     }
 }
-function launchHermesWalkthrough() {
-    const seedResult = spawn.sync('hermes', ['chat', '-Q', '-q', DEFAULT_ONBOARDING_PROMPT], {
+function launchHermesWalkthrough(prompt) {
+    const seedResult = spawn.sync('hermes', ['chat', '-Q', '-q', prompt], {
         encoding: 'utf8',
         timeout: HERMES_SEED_TIMEOUT_MS,
     });
@@ -100,18 +102,23 @@ function launchHermesWalkthrough() {
     }
     handOverTerminal('hermes', ['--resume', sessionId], 'Hermes');
 }
+function failedGate(detail, tag) {
+    return { ok: false, detail, tag };
+}
 /** Writes exit 0 having saved nothing, a disabled entry, or a keyless one. */
-export function hermesRegistrationEnabled(home) {
+export function hermesRegistrationEnabled(home, mode = 'api-key', expectedUrl) {
     const entry = readHermesEntry(home);
     if (entry.state === 'enabled') {
-        if (entry.usesKeyHeader)
+        if (expectedUrl && entry.url !== expectedUrl) {
+            return failedGate(`the entry still points at ${entry.url ?? 'an unknown URL'}`, 'hermes_entry_url_mismatch');
+        }
+        const validAuth = mode === 'keyless' ? entry.keyless : entry.usesKeyHeader;
+        if (validAuth)
             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',
-        };
+        return mode === 'keyless'
+            ? failedGate('the entry does not carry the keyless access header', 'hermes_entry_no_keyless_header')
+            : failedGate('the entry does not read the seeded key', 'hermes_entry_no_key_header');
     }
     // Each of these is a different repair, so none of them share wording.
     const detail = {
@@ -141,7 +148,15 @@ function registerHermesEntry(home, mcpUrl) {
             throw error;
         return false;
     }
-    return hermesRegistrationEnabled(home).ok;
+    return hermesRegistrationEnabled(home, 'api-key', mcpUrl).ok;
+}
+function registerHermesKeyless(home, mcpUrl) {
+    writeHermesMcpEntry(home, mcpUrl, 'keyless');
+    return hermesRegistrationEnabled(home, 'keyless', mcpUrl);
+}
+function prepareHermesKeylessInstall() {
+    const home = requireHermesHome();
+    return { home, register: (mcpUrl) => registerHermesKeyless(home, mcpUrl) };
 }
 function seedHermesKey(apiKey) {
     const home = requireHermesHome();
@@ -196,8 +211,8 @@ function installHermesWebPlugin({ apiKey, verbose, seededHome, }) {
 // OpenCode's TUI takes a positional as a project directory, so a bare `opencode "<prompt>"`
 // would be read as a folder. The `--prompt` flag seeds the interactive TUI with a first message
 // (opencode.ai/docs/cli), so the onboarding guide fires just like the other agents.
-function launchOpencode() {
-    handOverTerminal('opencode', ['--prompt', DEFAULT_ONBOARDING_PROMPT], 'OpenCode');
+function launchOpencode(prompt) {
+    handOverTerminal('opencode', ['--prompt', prompt], 'OpenCode');
 }
 /** "positional": flags before `tinyfish <url>`. "flag": flags after `--url`. */
 function specAddArgs(spec, mcpUrl) {
@@ -247,6 +262,13 @@ function specKeyAuth(spec) {
         addArgs: (mcpUrl, apiKey) => [...specAddArgs(spec, mcpUrl), '--header', value(apiKey)],
     };
 }
+function specKeylessAddArgs(spec) {
+    const { header } = spec;
+    if (!spec.keylessFallback || !header)
+        return undefined;
+    const value = `${TINYFISH_ACCESS_MODE_HEADER}${header.sep}${TINYFISH_KEYLESS_ACCESS_MODE}`;
+    return (mcpUrl) => specAddArgs(spec, mcpUrl).concat('--header', value);
+}
 /** Descriptor behaviour the spec cannot hold; every other field is spec data. */
 const HARNESS_OVERRIDES = {
     codex: { detachedLaunch: launchCodexWalkthrough },
@@ -255,6 +277,7 @@ const HARNESS_OVERRIDES = {
         extraPostInstall: installHermesWebPlugin,
         pluginVersion: HERMES_PLUGIN_VERSION,
         seedKey: seedHermesKey,
+        prepareKeylessInstall: prepareHermesKeylessInstall,
     },
     opencode: { launchWalkthrough: launchOpencode },
 };
@@ -273,6 +296,8 @@ function toNativeClient(harness) {
         skillAgent: spec.skillAgent,
         nonInteractiveAdd: spec.nonInteractiveAdd,
         keyAuth,
+        keylessAddArgs: specKeylessAddArgs(spec),
+        prepareKeylessInstall: overrides.prepareKeylessInstall,
         signInHint: spec.signInHint,
         degradedAuthNotes: spec.degradedAuthNotes,
         removals: spec.removals ?? [
@@ -329,21 +354,21 @@ async function deliverWalkthrough(displayName, command, prompt, handover, onDeci
     handover();
     return 'launched';
 }
-export async function launchNativeMcpClient(client, onDecided) {
+export async function launchNativeMcpClient(client, onDecided, prompt = DEFAULT_ONBOARDING_PROMPT) {
     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();
+        const outcome = client.detachedLaunch(prompt);
         await onDecided?.(outcome);
         return outcome;
     }
-    return deliverWalkthrough(client.displayName, client.command, DEFAULT_ONBOARDING_PROMPT, () => client.launchWalkthrough
-        ? client.launchWalkthrough()
-        : handOverTerminal(client.command, [DEFAULT_ONBOARDING_PROMPT], client.displayName), onDecided);
+    return deliverWalkthrough(client.displayName, client.command, prompt, () => client.launchWalkthrough
+        ? client.launchWalkthrough(prompt)
+        : handOverTerminal(client.command, [prompt], client.displayName), onDecided);
 }
 // Via deliverWalkthrough: handOverTerminal alone would wedge a headless --launch.
-export function launchOmpWalkthrough(onDecided) {
-    return deliverWalkthrough('omp', 'omp', DEFAULT_ONBOARDING_PROMPT, () => handOverTerminal('omp', [DEFAULT_ONBOARDING_PROMPT], 'omp'), onDecided);
+export function launchOmpWalkthrough(onDecided, prompt = DEFAULT_ONBOARDING_PROMPT) {
+    return deliverWalkthrough('omp', 'omp', prompt, () => handOverTerminal('omp', [prompt], 'omp'), onDecided);
 }
 export function launchPiWalkthrough(onDecided) {
     return deliverWalkthrough('Pi', 'pi', DEFAULT_ONBOARDING_PROMPT, () => handOverTerminal('pi', [DEFAULT_ONBOARDING_PROMPT], 'Pi'), onDecided);

package/dist/lib/constants.d.ts

@@ -8,6 +8,8 @@ export declare const CLI_AGENT_IDENTITY = "tinyfish-cli";
 export declare const WEB_SKILL_NAME = "use-tinyfish";
 /** The descriptor hands this name to harnesses; the probes resolve it. */
 export declare const TINYFISH_API_KEY_VAR = "TINYFISH_API_KEY";
+export declare const TINYFISH_ACCESS_MODE_HEADER = "X-TinyFish-Access-Mode";
+export declare const TINYFISH_KEYLESS_ACCESS_MODE = "keyless";
 export declare const BASE_URL: string;
 export declare const API_URL_OVERRIDE: string | undefined;
 /** URL where users can create and manage API keys */

package/dist/lib/constants.js

@@ -13,6 +13,8 @@ export const CLI_AGENT_IDENTITY = 'tinyfish-cli';
 export const WEB_SKILL_NAME = 'use-tinyfish';
 /** The descriptor hands this name to harnesses; the probes resolve it. */
 export const TINYFISH_API_KEY_VAR = 'TINYFISH_API_KEY';
+export const TINYFISH_ACCESS_MODE_HEADER = 'X-TinyFish-Access-Mode';
+export const TINYFISH_KEYLESS_ACCESS_MODE = 'keyless';
 /** Base URL for the TinyFish API. Override with TINYFISH_API_URL for staging/self-hosted. */
 const apiUrlOverride = process.env['TINYFISH_API_URL']?.trim() || undefined;
 if (apiUrlOverride) {

package/dist/lib/doctor-checks.js

@@ -298,6 +298,10 @@ export function checkHermesPlugin(status) {
     if (status.registered !== Registered.Yes) {
         return { check: { ...base, status: 'skip', detail: 'TinyFish is not registered in Hermes' } };
     }
+    const authMode = status.authMode === AuthMode.Unknown ? status.recordedAuthMode : status.authMode;
+    if (authMode === AuthMode.Keyless) {
+        return { check: { ...base, status: 'skip', detail: 'not needed for keyless Search' } };
+    }
     const resolved = resolveHermesHome();
     if (typeof resolved !== 'string') {
         return {

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

@@ -58,6 +58,7 @@ declare const doctorHarnessSchema: z.ZodObject<{
     registered: z.ZodEnum<typeof Registered>;
     auth_mode: z.ZodEnum<typeof AuthMode>;
     recorded_auth_mode: z.ZodOptional<z.ZodEnum<{
+        keyless: "keyless";
         "api-key": "api-key";
         oauth: "oauth";
         deferred: "deferred";
@@ -135,6 +136,7 @@ export declare const doctorReportSchema: z.ZodObject<{
         registered: z.ZodEnum<typeof Registered>;
         auth_mode: z.ZodEnum<typeof AuthMode>;
         recorded_auth_mode: z.ZodOptional<z.ZodEnum<{
+            keyless: "keyless";
             "api-key": "api-key";
             oauth: "oauth";
             deferred: "deferred";

package/dist/lib/doctor-report.js

@@ -20,7 +20,7 @@ const doctorHarnessSchema = z.object({
     registered: z.enum(Registered),
     auth_mode: z.enum(AuthMode),
     // Additive under schema 3: what connect wrote when the harness cannot echo it back.
-    recorded_auth_mode: z.enum(['api-key', 'oauth', 'deferred']).optional(),
+    recorded_auth_mode: z.enum(['api-key', 'keyless', 'oauth', 'deferred']).optional(),
     proves_harness_reach: z.boolean(),
 });
 // `action` is what `--fix` dispatches on, not the harness field: keying off a null harness

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

@@ -9,6 +9,7 @@ export declare enum Registered {
 }
 export declare enum AuthMode {
     ApiKey = "api-key",
+    Keyless = "keyless",
     OAuth = "oauth",
     Unknown = "unknown"
 }

package/dist/lib/harness-detect.js

@@ -17,6 +17,7 @@ export var Registered;
 export var AuthMode;
 (function (AuthMode) {
     AuthMode["ApiKey"] = "api-key";
+    AuthMode["Keyless"] = "keyless";
     AuthMode["OAuth"] = "oauth";
     AuthMode["Unknown"] = "unknown";
 })(AuthMode || (AuthMode = {}));

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

@@ -48,6 +48,7 @@ export interface HarnessSpec {
     keyedAddJsonFlags?: string[];
     /** No sign-in exists here, so connect refuses a keyless install (Hermes). */
     keyRequired?: true;
+    keylessFallback?: true;
     loginArgs?: string[];
     /** Default: one `mcp remove tinyfish` labeled from displayName. */
     removals?: {
@@ -199,6 +200,7 @@ export declare const HARNESS_SPECS: {
         reloadAction: string;
         skillAgent: "hermes-agent";
         keyRequired: true;
+        keylessFallback: true;
         supportCheck: {
             args: string[];
             patterns: RegExp[];
@@ -219,6 +221,7 @@ export declare const HARNESS_SPECS: {
         displayName: string;
         configDir: string;
         reloadAction: string;
+        keylessFallback: true;
         canVerifyAuth: true;
         keyHeldByCli: true;
         cliWritesConfig: true;
@@ -247,6 +250,7 @@ export declare const HARNESS_SPECS: {
         reloadAction: string;
         skillAgent: "opencode";
         nonInteractiveAdd: true;
+        keylessFallback: true;
         supportCheck: {
             args: string[];
             patterns: RegExp[];

package/dist/lib/harness-spec.js

@@ -177,6 +177,7 @@ export const HARNESS_SPECS = {
         reloadAction: 'restart it',
         skillAgent: 'hermes-agent',
         keyRequired: true,
+        keylessFallback: true,
         supportCheck: {
             args: ['mcp', 'add', '--help'],
             patterns: [/--auth\s+\{[^}]*oauth[^}]*\}/],
@@ -199,6 +200,7 @@ export const HARNESS_SPECS = {
         displayName: 'omp',
         configDir: '.omp',
         reloadAction: 'restart it',
+        keylessFallback: true,
         canVerifyAuth: true,
         keyHeldByCli: true,
         cliWritesConfig: true,
@@ -229,6 +231,7 @@ export const HARNESS_SPECS = {
         reloadAction: 'restart it',
         skillAgent: 'opencode',
         nonInteractiveAdd: true,
+        keylessFallback: true,
         supportCheck: {
             args: ['mcp', 'add', '--help'],
             patterns: [/--url(?:\s|$)/m],

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

@@ -13,9 +13,13 @@ export type HermesEntry = {
 } | {
     state: 'disabled';
     usesKeyHeader: boolean;
+    keyless?: true;
+    url?: string;
 } | {
     state: 'enabled';
     usesKeyHeader: boolean;
+    keyless?: true;
+    url?: string;
 };
 /** Connect's gate and doctor's probe share this, so they cannot disagree. */
 export declare function readHermesEntry(home: string): HermesEntry;

package/dist/lib/hermes-config.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parse } from 'yaml';
 import { z } from 'zod';
+import { TINYFISH_ACCESS_MODE_HEADER, TINYFISH_KEYLESS_ACCESS_MODE } from './constants.js';
 import { HERMES_KEY_VAR } from './hermes-env.js';
 /** Every message about the entry names this path. */
 export function hermesConfigPath(home) {
@@ -16,6 +17,7 @@ const entrySchema = z.looseObject({
     // Anything goes: the runtime defaults unrecognised values to enabled.
     enabled: z.unknown().optional(),
     headers: z.record(z.string(), z.unknown()).optional(),
+    url: z.unknown().optional(),
 });
 const configSchema = z
     .looseObject({
@@ -48,6 +50,10 @@ function hasKeyHeader(headers) {
     const authorization = Object.entries(headers ?? {}).find(([name]) => name.toLowerCase() === 'authorization');
     return authorization?.[1] === HERMES_HEADER_TEMPLATE;
 }
+function hasKeylessHeader(headers) {
+    const value = Object.entries(headers ?? {}).find(([name]) => name.toLowerCase() === TINYFISH_ACCESS_MODE_HEADER.toLowerCase())?.[1];
+    return typeof value === 'string' && value.trim().toLowerCase() === TINYFISH_KEYLESS_ACCESS_MODE;
+}
 /** Connect's gate and doctor's probe share this, so they cannot disagree. */
 export function readHermesEntry(home) {
     let raw;
@@ -68,7 +74,10 @@ export function readHermesEntry(home) {
     if (!entry)
         return { state: 'absent' };
     const usesKeyHeader = hasKeyHeader(entry.headers);
-    return isEnabled(entry.enabled)
-        ? { state: 'enabled', usesKeyHeader }
-        : { state: 'disabled', usesKeyHeader };
+    return {
+        state: isEnabled(entry.enabled) ? 'enabled' : 'disabled',
+        usesKeyHeader,
+        ...(hasKeylessHeader(entry.headers) ? { keyless: true } : {}),
+        ...(typeof entry.url === 'string' ? { url: entry.url } : {}),
+    };
 }

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

@@ -5,7 +5,7 @@ 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;
+export declare function writeHermesMcpEntry(home: string, mcpUrl: string, mode?: 'api-key' | 'keyless'): 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. */

package/dist/lib/hermes-plugin.js

@@ -6,7 +6,7 @@ import spawn from 'cross-spawn';
 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 { HARNESS_PROBE_TIMEOUT_MS, TINYFISH_ACCESS_MODE_HEADER, TINYFISH_KEYLESS_ACCESS_MODE, } 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.
@@ -97,15 +97,15 @@ function configWrite(home, args) {
     throw error;
 }
 /** Absent `enabled` reads as enabled, so never write this field-by-field. */
-export function writeHermesMcpEntry(home, mcpUrl) {
+export function writeHermesMcpEntry(home, mcpUrl, mode = 'api-key') {
     const entry = {
         url: mcpUrl,
-        headers: { Authorization: HERMES_HEADER_TEMPLATE },
+        headers: mode === 'keyless'
+            ? { [TINYFISH_ACCESS_MODE_HEADER]: TINYFISH_KEYLESS_ACCESS_MODE }
+            : { 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);
+    configWrite(home, ['set', `mcp_servers.${HERMES_MCP_SERVER_KEY}`, JSON.stringify(entry)]);
 }
 /** Retracts our row; an absent `enabled` reads as enabled, so a partial one is live. */
 export function removeHermesMcpEntry(home) {

package/dist/lib/mcp-json-config.d.ts

@@ -17,11 +17,13 @@ export interface McpJsonWriteResult {
     repaired?: boolean;
 }
 export declare function buildTinyfishServerEntry(mcpUrl: string, apiKey?: string): Record<string, unknown>;
+export declare function buildTinyfishKeylessServerEntry(mcpUrl: string): Record<string, unknown>;
 /** Dry-run description of the pending write; touches nothing. */
-export declare function planWrite(target: McpJsonTarget, mcpUrl: string, apiKey?: string): string;
+export declare function planWrite(target: McpJsonTarget, mcpUrl: string, apiKey?: string, serverEntry?: Record<string, unknown>): string;
 export interface McpJsonServerEntry {
     present: boolean;
     hasApiKeyHeader: boolean;
+    keyless?: true;
     /** Only ever false: harnesses with a disable toggle write it, the rest omit it. */
     enabled?: false;
     /** Registered endpoint, so a caller can tell "registered" from "registered at the right place". */
@@ -34,6 +36,6 @@ export interface McpJsonServerEntry {
 /** Reports the header's shape, never its value. */
 export declare function readTinyfishEntry(target: McpJsonTarget): McpJsonServerEntry;
 /** Merges only the target's key; skips unreadable/corrupt files rather than clobber. */
-export declare function writeMcpConfig(target: McpJsonTarget, mcpUrl: string, apiKey?: string): McpJsonWriteResult;
+export declare function writeMcpConfig(target: McpJsonTarget, mcpUrl: string, apiKey?: string, serverEntry?: Record<string, unknown>): McpJsonWriteResult;
 /** Removes only the target's key. */
 export declare function removeServer(target: McpJsonTarget): McpJsonWriteResult;

package/dist/lib/mcp-json-config.js

@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import { matchesCliKey } from './auth.js';
+import { TINYFISH_ACCESS_MODE_HEADER, TINYFISH_KEYLESS_ACCESS_MODE } from './constants.js';
 function isPlainRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -7,6 +8,9 @@ function isPlainRecord(value) {
 export function buildTinyfishServerEntry(mcpUrl, apiKey) {
     return apiKey ? { url: mcpUrl, headers: { 'X-API-Key': apiKey } } : { url: mcpUrl };
 }
+export function buildTinyfishKeylessServerEntry(mcpUrl) {
+    return { url: mcpUrl, headers: { [TINYFISH_ACCESS_MODE_HEADER]: TINYFISH_KEYLESS_ACCESS_MODE } };
+}
 function parseMcpJson(raw) {
     try {
         const parsed = JSON.parse(raw);
@@ -38,18 +42,21 @@ function readExisting(target) {
     return { raw, parsed: parsed.value };
 }
 /** Dry-run description of the pending write; touches nothing. */
-export function planWrite(target, mcpUrl, apiKey) {
+export function planWrite(target, mcpUrl, apiKey, serverEntry) {
     const existing = readExisting(target);
     const filePath = target.file();
     if ('error' in existing) {
         return `${filePath}: existing file is corrupt (${existing.error}) — would skip and leave it untouched`;
     }
-    const authNote = apiKey
-        ? ' with an API-key header — the key is stored in plaintext in that file (value not shown here)'
-        : '';
+    const authNote = serverEntry
+        ? ` with an ${TINYFISH_ACCESS_MODE_HEADER}: ${TINYFISH_KEYLESS_ACCESS_MODE} header`
+        : apiKey
+            ? ' with an API-key header — the key is stored in plaintext in that file (value not shown here)'
+            : '';
+    const nextEntry = serverEntry ?? buildTinyfishServerEntry(mcpUrl, apiKey);
     const servers = existing.parsed.mcpServers;
     const current = isPlainRecord(servers) ? servers[target.serverKey] : undefined;
-    if (JSON.stringify(current) === JSON.stringify(buildTinyfishServerEntry(mcpUrl, apiKey))) {
+    if (JSON.stringify(current) === JSON.stringify(nextEntry)) {
         return `${filePath}: already has the ${target.serverKey} MCP entry — no change`;
     }
     return existing.raw === undefined
@@ -61,17 +68,21 @@ const ENV_TEMPLATE_VALUE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-[^}]*)?\}$/;
 /** Reports the header's shape, never its value. */
 export function readTinyfishEntry(target) {
     const existing = readExisting(target);
-    if ('error' in existing)
+    if ('error' in existing) {
         return { present: false, hasApiKeyHeader: false, error: existing.error };
+    }
     const servers = existing.parsed.mcpServers;
     const entry = isPlainRecord(servers) ? servers[target.serverKey] : undefined;
     if (!isPlainRecord(entry))
         return { present: false, hasApiKeyHeader: false };
     const key = readKeyHeader(entry.headers, target.keyHeader);
     const templateVar = key ? ENV_TEMPLATE_VALUE.exec(key.value)?.[1] : undefined;
+    const accessMode = readKeyHeader(entry.headers, { name: TINYFISH_ACCESS_MODE_HEADER })?.value;
+    const keyless = accessMode?.trim().toLowerCase() === TINYFISH_KEYLESS_ACCESS_MODE;
     return {
         present: true,
         hasApiKeyHeader: key !== undefined,
+        ...(keyless ? { keyless: true } : {}),
         ...(entry.enabled === false ? { enabled: false } : {}),
         ...(matchesCliKey(key?.value) ? { keyMatchesCliKey: true } : {}),
         ...(templateVar ? { keyTemplateVar: templateVar } : {}),
@@ -114,19 +125,18 @@ function commitServers(target, existing, servers) {
     return { status: 'written', backupPath };
 }
 /** Merges only the target's key; skips unreadable/corrupt files rather than clobber. */
-export function writeMcpConfig(target, mcpUrl, apiKey) {
+export function writeMcpConfig(target, mcpUrl, apiKey, serverEntry = buildTinyfishServerEntry(mcpUrl, apiKey)) {
     const existing = readExisting(target);
     if ('error' in existing)
         return { status: 'corrupt_skip', error: existing.error };
     const servers = isPlainRecord(existing.parsed.mcpServers)
         ? { ...existing.parsed.mcpServers }
         : {};
-    const nextEntry = buildTinyfishServerEntry(mcpUrl, apiKey);
-    if (JSON.stringify(servers[target.serverKey]) === JSON.stringify(nextEntry)) {
+    if (JSON.stringify(servers[target.serverKey]) === JSON.stringify(serverEntry)) {
         return { status: 'unchanged' };
     }
     const repaired = target.serverKey in servers;
-    servers[target.serverKey] = nextEntry;
+    servers[target.serverKey] = serverEntry;
     return { ...commitServers(target, existing, servers), repaired };
 }
 /** Removes only the target's key. */

package/dist/lib/omp-config.js

@@ -2,7 +2,7 @@ import * as path from 'path';
 import spawn from 'cross-spawn';
 import { ConnectStepError } from './connect-runtime.js';
 import { HARNESS_PROBE_TIMEOUT_MS } from './constants.js';
-import { planWrite, readTinyfishEntry, removeServer, writeMcpConfig, } from './mcp-json-config.js';
+import { buildTinyfishKeylessServerEntry, planWrite, readTinyfishEntry, removeServer, writeMcpConfig, } from './mcp-json-config.js';
 const UNRESOLVED_REASON = '`omp config path` did not report a config directory';
 // Cached: every later read must agree with the write.
 let cachedAgentDir;
@@ -53,14 +53,16 @@ export function readOmpTinyfishEntry() {
 }
 /** Merges only the `tinyfish` key; throws when the dir is unresolved. */
 export function writeOmpMcpConfig(mcpUrl, apiKey) {
-    return writeMcpConfig(requireOmpTarget(), mcpUrl, apiKey);
+    const entry = apiKey ? undefined : buildTinyfishKeylessServerEntry(mcpUrl);
+    return writeMcpConfig(requireOmpTarget(), mcpUrl, apiKey, entry);
 }
 /** Dry-run description of the pending write; touches nothing. */
 export function planOmpWrite(mcpUrl, apiKey) {
     const target = ompMcpTarget();
     if (!target)
         return `${UNRESOLVED_REASON} — connect omp would fail the same way`;
-    return planWrite(target, mcpUrl, apiKey);
+    const entry = apiKey ? undefined : buildTinyfishKeylessServerEntry(mcpUrl);
+    return planWrite(target, mcpUrl, apiKey, entry);
 }
 /** Removes only the `tinyfish` key. */
 export function removeOmpMcpServer() {