@tiny-fish/cli 0.33.1-next.279 → 0.33.1-next.281

package/dist/commands/connect.js

@@ -72,7 +72,7 @@ function refuseKeylessInstall(client, keyAuthSupported) {
             `Update it, then ${rerun}`, 'harness_too_old');
     }
     throw new ConnectStepError(`Connecting ${client.displayName} needs a TinyFish API key, and ${noSignIn}. ` +
-        `Run: tinyfish auth login, then ${rerun}`, 'invalid_config');
+        `Run: tinyfish auth login, then ${rerun}`, 'invalid_config', { failureDetail: 'keyless_install_refused' });
 }
 /** Resolved before the removals, so a refusal strands no registration. */
 function keylessAddArgs(client, keyAuthSupported, oauthResource) {
@@ -92,8 +92,9 @@ async function verifyKeyBeforeSeeding(apiKey, displayName, mcpUrl) {
         throw new ConnectStepError(`Could not reach TinyFish to check your API key (${verified.code ?? 'unknown'}), so ` +
             `nothing was written to ${displayName}. Check your connection and retry.`, 'timeout');
     }
+    // The tag carries the HTTP status; `verified.code` is authored prose.
     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');
+        `written to ${displayName}. Run: tinyfish auth login`, 'invalid_config', { failureDetail: `key_rejected status=${verified.status}` });
 }
 /** A bounded spawn's timeout means the sign-in never finished. */
 function signInStepError(message, result, bounded) {
@@ -213,7 +214,9 @@ function performMcpAdd(client, options, plan, attemptId) {
     const registration = seeded?.confirmRegistered();
     if (registration && !registration.ok) {
         failAdd(() => new ConnectStepError(`${client.displayName} reported success but TinyFish is not enabled there` +
-            `${registration.detail ? `: ${registration.detail}` : ''}.`, 'invalid_config'));
+            `${registration.detail ? `: ${registration.detail}` : ''}.`, 'invalid_config', 
+        // The tag keeps the path-bearing prose out of telemetry.
+        { failureDetail: registration.tag }));
     }
     return seeded?.note;
 }
@@ -423,6 +426,7 @@ function trackPostInstallFailure(displayName, state, telemetry, error) {
         telemetry.track('post_install_failed', {
             failedStage: state.stage,
             failureReason: error instanceof ConnectStepError ? error.failureReason : 'unexpected_error',
+            failureDetail: error instanceof ConnectStepError ? (error.failureDetail ?? error.message) : undefined,
             stageDurationMs: stageDurationOf(error),
         });
     }
@@ -570,8 +574,9 @@ export async function connectCursor(options) {
         mcpUrl.searchParams.set('connect_attempt_id', telemetry.attemptId);
         const result = writeCursorMcpConfig(mcpUrl.toString(), resolvedKey);
         if (result.status === 'corrupt_skip') {
+            // The message fallback would leak the config path; tag instead.
             throw new ConnectStepError(`Could not update ${cursorMcpPath()}: existing file could not be read or is not valid JSON (${result.error}). ` +
-                `Fix the file, then re-run: tinyfish connect cursor`, 'invalid_config');
+                `Fix the file, then re-run: tinyfish connect cursor`, 'invalid_config', { failureDetail: 'cursor_mcp_json_corrupt' });
         }
         if (result.backupPath) {
             errLine(`Backed up existing Cursor MCP config to ${result.backupPath}`);

package/dist/commands/search.js

@@ -1,9 +1,10 @@
 import { getApiKey } from '../lib/auth.js';
 import { searchQuery } from '../lib/client.js';
-import { handleApiError, out, outLine } from '../lib/output.js';
+import { err, handleApiError, out, outLine } from '../lib/output.js';
 function printPrettySearch(response) {
     outLine(`Query: ${response.query}`);
     outLine(`Total results: ${response.total_results}`);
+    outLine(`Page: ${response.page}`);
     outLine('');
     if (response.results.length === 0) {
         outLine('No results.');
@@ -16,6 +17,16 @@ function printPrettySearch(response) {
         outLine('');
     }
 }
+// Blank strings coerce to 0, a valid page.
+function parsePageOption(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value) || Number(value) > 10) {
+        err({ error: `Invalid --page "${value}". Must be an integer between 0 and 10.` });
+        process.exit(1);
+    }
+    return Number(value);
+}
 export function registerSearch(program) {
     const searchCmd = program
         .command('search')
@@ -29,8 +40,10 @@ export function registerSearch(program) {
         .option('--language <value>', 'Search language hint')
         .option('--include-domains <value>', 'Comma-separated list of domains to restrict results to')
         .option('--exclude-domains <value>', 'Comma-separated list of domains to exclude from results')
+        .option('--page <value>', 'Page number for pagination, starting from 0')
         .option('--pretty', 'Human-readable output')
         .action(async (query, opts) => {
+        const page = parsePageOption(opts.page);
         const apiKey = getApiKey();
         try {
             const response = await searchQuery({
@@ -39,6 +52,7 @@ export function registerSearch(program) {
                 ...(opts.language !== undefined ? { language: opts.language } : {}),
                 ...(opts.includeDomains !== undefined ? { include_domains: opts.includeDomains } : {}),
                 ...(opts.excludeDomains !== undefined ? { exclude_domains: opts.excludeDomains } : {}),
+                ...(page !== undefined ? { page } : {}),
             }, apiKey);
             if (opts.pretty) {
                 printPrettySearch(response);

package/dist/lib/connect-auth.js

@@ -8,7 +8,9 @@ export function ensureCliAuthenticated(source, apiKey, opts) {
     const envKey = apiKey ?? process.env[TINYFISH_API_KEY_VAR];
     if (envKey) {
         if (!validateKeyFormat(envKey)) {
-            throw new ConnectStepError('TINYFISH_API_KEY has invalid format', 'invalid_config');
+            throw new ConnectStepError('TINYFISH_API_KEY has invalid format', 'invalid_config', {
+                failureDetail: 'env_key_invalid_format',
+            });
         }
         // Throwing variant: a write failure must reach connect's catch/flush, not exit(1) past it.
         writeConfig(envKey);

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

@@ -32,6 +32,7 @@ export interface SeededInstall {
     confirmRegistered: () => {
         ok: boolean;
         detail?: string;
+        tag?: string;
     };
 }
 interface BaseMcpClient extends SupportedCommand {
@@ -97,6 +98,7 @@ export declare const GROK: NativeMcpClient;
 export declare function hermesRegistrationEnabled(home: string): {
     ok: boolean;
     detail?: string;
+    tag?: string;
 };
 export declare const HERMES: KeyRequiredMcpClient;
 export declare const OPENCODE: NativeMcpClient;

package/dist/lib/connect-clients.js

@@ -256,13 +256,14 @@ export function hermesRegistrationEnabled(home) {
         unreadable: `${hermesConfigPath(home)} could not be read`,
         unparseable: `${hermesConfigPath(home)} could not be parsed`,
     }[entry.state];
-    return { ok: false, detail };
+    // The tag keeps the path-bearing prose out of telemetry.
+    return { ok: false, detail, tag: `hermes_entry_${entry.state}` };
 }
 function seedHermesKey(apiKey) {
     const home = resolveHermesHome();
     // A plain Error settles unexpected_error; cli_connect_stage is load-bearing.
     if (!home) {
-        throw new ConnectStepError("Could not determine Hermes' home directory from `hermes dump`", 'invalid_config');
+        throw new ConnectStepError("Could not determine Hermes' home directory from `hermes dump`", 'invalid_config', { failureDetail: 'hermes_home_undetermined' });
     }
     const restore = captureHermesKeyRestore(home);
     writeHermesKey(home, apiKey);

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

@@ -18,9 +18,11 @@ export declare class HoistedFailureReportedError extends Error {
 export declare class ConnectStepError extends Error {
     readonly failureReason: ConnectFailureReason;
     readonly harnessVersion?: string;
+    readonly failureDetail?: string;
     constructor(message: string, failureReason: ConnectFailureReason, opts?: {
         harnessVersion?: string;
         cause?: unknown;
+        failureDetail?: string;
     });
 }
 /** Hoisted install predates this attempt's telemetry; the gap reads ~0 ms. */
@@ -38,11 +40,15 @@ export interface SpawnStepResult {
     status?: number | null;
     signal?: string | null;
     error?: Error;
+    /** Inherited stdio leaves this null; only piped runs yield text. */
+    stderr?: unknown;
 }
 /** Bounded removal spawn shared by install cleanup and --uninstall; Ctrl+C throws. */
 export declare function spawnRemoval(command: string, args: readonly string[], timeoutMs?: number): import("child_process").SpawnSyncReturns<string>;
+/** Outcome plus a bounded stderr tail; the route sanitizes and caps the rest. */
+export declare function spawnFailureDetail(result: SpawnStepResult): string;
 /** Classifies a spawn failure; interrupts throw instead. */
-export declare function spawnStepError(message: string, result: SpawnStepResult): ConnectStepError;
+export declare function spawnStepError(message: string, result: SpawnStepResult, failureDetail?: string): ConnectStepError;
 export declare function commandNotFound(error: unknown): boolean;
 /** One command redoes every post-install step for a client. */
 export declare function finishSetupCommand(client: AgentClient): string;
@@ -64,6 +70,8 @@ interface ConnectStageDetail {
     harnessDegraded?: boolean;
     /** Overrides the event-gap duration; the hoisted CLI install measures itself. */
     stageDurationMs?: number;
+    /** Dropped from the wire unless `failedStage` is set (route refine). */
+    failureDetail?: string;
 }
 export interface ConnectTelemetry {
     attemptId: string;

package/dist/lib/connect-runtime.js

@@ -32,10 +32,12 @@ export class HoistedFailureReportedError extends Error {
 export class ConnectStepError extends Error {
     failureReason;
     harnessVersion;
+    failureDetail;
     constructor(message, failureReason, opts) {
         super(message, { cause: opts?.cause });
         this.failureReason = failureReason;
         this.harnessVersion = opts?.harnessVersion;
+        this.failureDetail = opts?.failureDetail;
     }
 }
 /** Hoisted install predates this attempt's telemetry; the gap reads ~0 ms. */
@@ -76,8 +78,19 @@ export function spawnRemoval(command, args, timeoutMs = NON_INTERACTIVE_TIMEOUT_
     throwIfInterrupted(result);
     return result;
 }
+// Sanitized before the cut so the count is not spent on invisible bytes.
+const STDERR_TAIL_MAX_CHARS = 400;
+/** Outcome plus a bounded stderr tail; the route sanitizes and caps the rest. */
+export function spawnFailureDetail(result) {
+    const stderr = typeof result.stderr === 'string'
+        ? sanitizeLine(result.stderr.trim()).slice(-STDERR_TAIL_MAX_CHARS)
+        : '';
+    // A signal kill leaves status null, where the signal is the diagnosis.
+    const outcome = result.signal ? `signal=${result.signal}` : `exit=${result.status}`;
+    return `${outcome}${stderr ? ` | ${stderr}` : ''}`;
+}
 /** Classifies a spawn failure; interrupts throw instead. */
-export function spawnStepError(message, result) {
+export function spawnStepError(message, result, failureDetail) {
     throwIfInterrupted(result);
     const code = result.error?.code;
     const reason = !result.error
@@ -87,7 +100,8 @@ export function spawnStepError(message, result) {
             : code === 'ETIMEDOUT'
                 ? 'timeout'
                 : 'spawn_error';
-    return new ConnectStepError(message, reason, { cause: result.error });
+    const detail = failureDetail ?? (reason === 'nonzero_exit' ? spawnFailureDetail(result) : undefined);
+    return new ConnectStepError(message, reason, { cause: result.error, failureDetail: detail });
 }
 export function commandNotFound(error) {
     return error?.code === 'ENOENT';
@@ -136,7 +150,11 @@ export async function runGuarded(state, telemetry, body) {
         }
         // An elapsed sign-in wait is abandonment, not breakage.
         if (error instanceof SignInTimeoutError) {
-            settle(state, telemetry, 'aborted', { failedStage: state.stage, failureReason: 'timeout' });
+            settle(state, telemetry, 'aborted', {
+                failedStage: state.stage,
+                failureReason: 'timeout',
+                failureDetail: error.failureDetail ?? error.message,
+            });
             throw error;
         }
         // An earlier attempt owns the shared failure's terminal row.
@@ -145,7 +163,12 @@ export async function runGuarded(state, telemetry, body) {
         settle(state, telemetry, 'failed', {
             failedStage: state.stage,
             failureReason: error instanceof ConnectStepError ? error.failureReason : 'unexpected_error',
-            ...(error instanceof ConnectStepError ? { harnessVersion: error.harnessVersion } : {}),
+            ...(error instanceof ConnectStepError
+                ? {
+                    harnessVersion: error.harnessVersion,
+                    failureDetail: error.failureDetail ?? error.message,
+                }
+                : {}),
             stageDurationMs: stageDurationOf(error),
         });
         throw error;
@@ -227,6 +250,12 @@ function takeSeedAttemptId() {
     const parked = takePendingConnectAttempt();
     return fromEnv && isAttemptId(fromEnv) ? fromEnv : parked;
 }
+// postConnectEvent is total, so this only fires on a bug inside deliver.
+function reportDeliverBug(error) {
+    if (!process.env['TINYFISH_DEBUG'])
+        return;
+    errLine(`connect telemetry failed: ${error instanceof Error ? error.message : String(error)}`);
+}
 export function createConnectTelemetry(mcpUrl, client, opts) {
     // Consumed even when --url already supplied an id: leaving it behind would let a stale
     // seed reach the agent this connect launches, or the next connect on this machine.
@@ -252,6 +281,33 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
             label: 'connect',
         });
     }
+    function eventBody(stage, detail, stageDurationMs) {
+        return JSON.stringify({
+            attempt_id: attemptId,
+            client,
+            stage,
+            failed_stage: detail?.failedStage,
+            phase: detail?.phase,
+            failure_reason: detail?.failureReason,
+            // Only with failed_stage: the route refine 400s the event otherwise.
+            failure_detail: detail?.failedStage ? detail.failureDetail : undefined,
+            // Terminal rows only: rescue checkpoints stay wire-identical to normal ones.
+            fallback_outcome: stage === 'failed' || stage === 'aborted' ? fallbackOutcome : undefined,
+            harness_version: detail?.harnessVersion ?? harnessVersion,
+            auth_mode: detail?.authMode,
+            harness_degraded: detail?.harnessDegraded,
+            stage_duration_ms: stageDurationMs,
+            runtime_platform: process.platform,
+            node_version: process.version,
+            cli_version: CLI_VERSION,
+            // Same signal the usage events carry, so TTY and headless connects can be split.
+            is_human_initiated: detectHumanInitiated(),
+            // "none", not absent — absent has to keep meaning "CLI too old".
+            calling_harness: detectHarness() ?? 'none',
+            cli_invocation_id: CLI_INVOCATION_ID,
+            runtime_env: detectRuntimeEnv(),
+        });
+    }
     return {
         attemptId,
         // Fire-and-forget; awaiting each event stalls setup when telemetry down.
@@ -269,35 +325,7 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
             lastTrackAt = now;
             // Absorbed here, not in flush: flush runs in runGuarded's finally, so a rejection would
             // replace the error the flow is already reporting.
-            pending.push(deliver(JSON.stringify({
-                attempt_id: attemptId,
-                client,
-                stage,
-                failed_stage: detail?.failedStage,
-                phase: detail?.phase,
-                failure_reason: detail?.failureReason,
-                // Terminal rows only: rescue checkpoints stay wire-identical to normal ones.
-                fallback_outcome: stage === 'failed' || stage === 'aborted' ? fallbackOutcome : undefined,
-                harness_version: detail?.harnessVersion ?? harnessVersion,
-                auth_mode: detail?.authMode,
-                harness_degraded: detail?.harnessDegraded,
-                stage_duration_ms: stageDurationMs,
-                runtime_platform: process.platform,
-                node_version: process.version,
-                cli_version: CLI_VERSION,
-                // Same signal the usage events carry, so TTY and headless connects can be split.
-                is_human_initiated: detectHumanInitiated(),
-                // "none", not absent — absent has to keep meaning "CLI too old".
-                calling_harness: detectHarness() ?? 'none',
-                cli_invocation_id: CLI_INVOCATION_ID,
-                runtime_env: detectRuntimeEnv(),
-            })).catch((error) => {
-                // postConnectEvent is total, so this only fires if something inside deliver starts
-                // throwing. Same channel postConnectEvent uses for its own failures.
-                if (!process.env['TINYFISH_DEBUG'])
-                    return;
-                errLine(`connect telemetry failed: ${error instanceof Error ? error.message : String(error)}`);
-            }));
+            pending.push(deliver(eventBody(stage, detail, stageDurationMs)).catch(reportDeliverBug));
         },
         // Awaited in finally so in-flight events land before exit. Drains, so the signal-guard
         // flush and the finally flush do not re-await the same events.

package/dist/lib/skill-install.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { loadConfig } from './auth.js';
 import { captureStdio, capturedOutput, replay, SKILL_INSTALL_TIMEOUT_MS, STEP_MAX_BUFFER, } from './cli-install.js';
 import { CURSOR_SKILL_TARGET, NATIVE_MCP_CLIENTS, OPENCLAW_SKILL_INSTALL_ARGS, } from './connect-clients.js';
-import { commandNotFound, spawnStepError, throwIfInterrupted } from './connect-runtime.js';
+import { commandNotFound, spawnFailureDetail, spawnStepError, throwIfInterrupted, } from './connect-runtime.js';
 import { CLI_AGENT_IDENTITY } from './constants.js';
 import { errLine } from './output.js';
 // Supports Hermes without node:util.styleText, so the installer still runs on Node 20.11.
@@ -53,8 +53,12 @@ function failedListVerdict() {
         maxBuffer: STEP_MAX_BUFFER,
         timeout: SKILL_INSTALL_TIMEOUT_MS,
     });
-    const verified = !list.error && list.status === 0 && skillListed(list.stdout ?? '');
-    return verified ? null : list;
+    const listRan = !list.error && list.status === 0;
+    if (listRan && skillListed(list.stdout ?? ''))
+        return null;
+    // A clean list that omits the skill is not a real exit (PF-3680).
+    const tag = listRan ? 'skill_absent_after_add' : `skill_list_failed ${spawnFailureDetail(list)}`;
+    return { result: list, tag };
 }
 // Entry presence is the whole verdict: `agents` names the harnesses `skills` detects,
 // so an install for a harness with no config dir yet lists none (PF-3680).
@@ -78,10 +82,12 @@ export function installWebSkill(client, { verbose }) {
         ...captureStdio(verbose),
         env: skillSpawnEnv(),
     });
-    const failed = add.error || add.status !== 0 ? add : failedListVerdict();
+    const addFailed = Boolean(add.error) || add.status !== 0;
+    const verdict = addFailed ? null : failedListVerdict();
+    const failed = addFailed ? add : verdict?.result;
     if (failed) {
         // Built first: its interrupt check must run before any replay.
-        const error = spawnStepError(`Could not install the TinyFish web skill in ${client.displayName}`, failed);
+        const error = spawnStepError(`Could not install the TinyFish web skill in ${client.displayName}`, failed, verdict?.tag);
         // The add carries the failure prose; the list is JSON only.
         replay(capturedOutput(add));
         throw error;
@@ -154,12 +160,12 @@ function reinstallWebSkill(skillAgents, verbose) {
     const failedList = addFailed ? null : failedListVerdict();
     const failed = addFailed || failedList !== null;
     if (failed)
-        throwIfInterrupted(failedList ?? result);
+        throwIfInterrupted(failedList?.result ?? result);
     if (verbose || failed)
         replay(output);
     if (failed) {
         throw new Error('Could not refresh the TinyFish web skill', {
-            cause: (failedList ?? result).error,
+            cause: (failedList?.result ?? result).error,
         });
     }
 }

package/package.json

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