@tiny-fish/cli 0.39.1-next.311 → 0.40.1-next.317

package/README.md

@@ -278,6 +278,13 @@ tinyfish fetch content get https://agentql.com --links --image-links
 # Bound each URL independently
 tinyfish fetch content get https://agentql.com --per-url-timeout-ms 45000
 
+# Ranked verbatim snippets answering a query (beta; markdown only, max 10 URLs)
+tinyfish fetch content get https://agentql.com --highlights "pricing tiers"
+
+# Tune snippets: count (1-20, default 5), total characters, keep full-page text
+tinyfish fetch content get https://agentql.com --highlights "pricing tiers" \
+  --max-snippets 3 --max-characters 1200 --include-full-page-text
+
 # Human-readable output
 tinyfish fetch content get https://agentql.com --pretty
 ```

package/dist/commands/connect.js

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

package/dist/commands/doctor.js

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

package/dist/commands/fetch.js

@@ -4,14 +4,64 @@ import { fetchContentGet } from '../lib/client.js';
 import { err, handleApiError, out, outLine } from '../lib/output.js';
 const MIN_PER_URL_TIMEOUT_MS = 1;
 const MAX_PER_URL_TIMEOUT_MS = 110000;
-function parsePerUrlTimeoutMs(value) {
-    const parsed = Number(value);
-    if (!Number.isInteger(parsed) ||
-        parsed < MIN_PER_URL_TIMEOUT_MS ||
-        parsed > MAX_PER_URL_TIMEOUT_MS) {
-        throw new InvalidArgumentError(`must be an integer between ${MIN_PER_URL_TIMEOUT_MS} and ${MAX_PER_URL_TIMEOUT_MS}`);
+const MIN_HIGHLIGHT_SNIPPETS = 1;
+const MAX_HIGHLIGHT_SNIPPETS = 20;
+const MAX_URLS = 10;
+function integerInRange(min, max) {
+    return (value) => {
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || parsed < min || (max !== undefined && parsed > max)) {
+            throw new InvalidArgumentError(max === undefined
+                ? 'must be a positive integer'
+                : `must be an integer between ${min} and ${max}`);
+        }
+        return parsed;
+    };
+}
+function validateHighlightsOptions(opts) {
+    const hasSubFlag = opts.maxSnippets !== undefined ||
+        opts.maxCharacters !== undefined ||
+        opts.includeFullPageText !== undefined;
+    if (opts.highlights === undefined) {
+        return hasSubFlag
+            ? '--max-snippets, --max-characters and --include-full-page-text require --highlights'
+            : null;
+    }
+    if (opts.highlights.trim() === '') {
+        return '--highlights requires a non-empty query';
     }
-    return parsed;
+    if (opts.format !== undefined && opts.format !== 'markdown') {
+        return '--highlights requires --format markdown';
+    }
+    return null;
+}
+function buildHighlightsParams(opts) {
+    if (opts.highlights === undefined)
+        return undefined;
+    return {
+        query: opts.highlights,
+        ...(opts.maxSnippets !== undefined ? { max_snippets: opts.maxSnippets } : {}),
+        ...(opts.maxCharacters !== undefined ? { max_characters: opts.maxCharacters } : {}),
+        ...(opts.includeFullPageText !== undefined
+            ? { include_full_page_text: opts.includeFullPageText }
+            : {}),
+    };
+}
+function buildFetchParams(urls, opts) {
+    const highlights = buildHighlightsParams(opts);
+    return {
+        urls,
+        ...(opts.format !== undefined ? { format: opts.format } : {}),
+        ...(opts.links !== undefined ? { links: opts.links } : {}),
+        ...(opts.imageLinks !== undefined ? { image_links: opts.imageLinks } : {}),
+        ...(opts.perUrlTimeoutMs !== undefined ? { per_url_timeout_ms: opts.perUrlTimeoutMs } : {}),
+        ...(opts.ifNoneMatch !== undefined ? { if_none_match: opts.ifNoneMatch } : {}),
+        ...(opts.ifModifiedSince !== undefined ? { if_modified_since: opts.ifModifiedSince } : {}),
+        ...(opts.includeEtagAndLastModified !== undefined
+            ? { include_etag_and_last_modified: opts.includeEtagAndLastModified }
+            : {}),
+        ...(highlights !== undefined ? { highlights } : {}),
+    };
 }
 function printPrettyFetch(response) {
     outLine(`Results: ${response.results.length}`);
@@ -32,6 +82,12 @@ function printPrettyFetch(response) {
                 outLine(`  ETag: ${result.etag}`);
             if (result.last_modified)
                 outLine(`  Last-Modified: ${result.last_modified}`);
+            if (result.highlights && result.highlights.length > 0) {
+                outLine('  Highlights:');
+                result.highlights.forEach((snippet, index) => {
+                    outLine(`    ${index + 1}. ${snippet.text}`);
+                });
+            }
             outLine('');
         }
     }
@@ -57,12 +113,26 @@ export function registerFetch(program) {
         .option('--format <format>', 'Output format: markdown, html, or json')
         .option('--links', 'Include extracted links')
         .option('--image-links', 'Include extracted image links')
-        .option('--per-url-timeout-ms <milliseconds>', 'Per-URL timeout budget in milliseconds', parsePerUrlTimeoutMs)
+        .option('--per-url-timeout-ms <milliseconds>', 'Per-URL timeout budget in milliseconds', integerInRange(MIN_PER_URL_TIMEOUT_MS, MAX_PER_URL_TIMEOUT_MS))
         .option('--if-none-match <etag>', 'ETag validator for a conditional GET (single URL only)')
         .option('--if-modified-since <http-date>', 'Last-Modified validator for a conditional GET (single URL only)')
         .option('--include-etag-and-last-modified', 'Include etag / last_modified validators on each result')
+        .option('--highlights <query>', '(beta) Return ranked verbatim snippets answering the query instead of full-page text (markdown only, max 10 URLs)')
+        .option('--max-snippets <n>', 'Maximum snippets per URL, 1-20 (default 5; requires --highlights)', integerInRange(MIN_HIGHLIGHT_SNIPPETS, MAX_HIGHLIGHT_SNIPPETS))
+        .option('--max-characters <n>', 'Maximum total characters across snippets (requires --highlights)', integerInRange(1))
+        .option('--include-full-page-text', 'Also return full-page text alongside snippets (requires --highlights)')
         .option('--pretty', 'Human-readable output')
         .action(async (urls, opts) => {
+        // Mirrors the SDK cap the raw post path no longer enforces.
+        if (urls.length > MAX_URLS) {
+            err({ error: `urls must contain at most ${MAX_URLS} items` });
+            process.exit(1);
+        }
+        const highlightsError = validateHighlightsOptions(opts);
+        if (highlightsError !== null) {
+            err({ error: highlightsError });
+            process.exit(1);
+        }
         if ((opts.ifNoneMatch !== undefined || opts.ifModifiedSince !== undefined) &&
             urls.length > 1) {
             err({
@@ -72,22 +142,7 @@ export function registerFetch(program) {
         }
         const apiKey = getApiKey();
         try {
-            const response = await fetchContentGet({
-                urls,
-                ...(opts.format !== undefined ? { format: opts.format } : {}),
-                ...(opts.links !== undefined ? { links: opts.links } : {}),
-                ...(opts.imageLinks !== undefined ? { image_links: opts.imageLinks } : {}),
-                ...(opts.perUrlTimeoutMs !== undefined
-                    ? { per_url_timeout_ms: opts.perUrlTimeoutMs }
-                    : {}),
-                ...(opts.ifNoneMatch !== undefined ? { if_none_match: opts.ifNoneMatch } : {}),
-                ...(opts.ifModifiedSince !== undefined
-                    ? { if_modified_since: opts.ifModifiedSince }
-                    : {}),
-                ...(opts.includeEtagAndLastModified !== undefined
-                    ? { include_etag_and_last_modified: opts.includeEtagAndLastModified }
-                    : {}),
-            }, apiKey);
+            const response = await fetchContentGet(buildFetchParams(urls, opts), apiKey);
             if (opts.pretty) {
                 printPrettyFetch(response);
             }

package/dist/lib/client.d.ts

@@ -1,5 +1,6 @@
-import { type AgentRunAsyncResponse, type AgentRunResponse, type AgentRunWithStreamingResponse, type FetchGetContentsParams, type FetchResponse, type BrowserSession, type Run, type RunListParams, type RunListResponse, type SearchQueryParams, type SearchQueryResponse, type WalletResponse } from '@tiny-fish/sdk';
-import type { BatchCancelResponse, BatchGetResponse, BatchRunRequest, BatchRunResponse, CancelRunResponse, CliAgentRunParams, CliBrowserSessionCreateParams, CookieRecord, ProfileCreateResponse, ProfileUploadResponse, RunStepsResponse, VaultConnectRequest, VaultConnectResponse, VaultConnectionsListResponse, VaultDisconnectResponse, VaultItemsListResponse, VaultItemsSyncResponse } from './types.js';
+import { type AgentRunAsyncResponse, type AgentRunResponse, type AgentRunWithStreamingResponse, type BrowserSession, type Run, type RunListParams, type RunListResponse, type SearchQueryParams, type SearchQueryResponse, type WalletResponse } from '@tiny-fish/sdk';
+import type { BatchCancelResponse, BatchGetResponse, BatchRunRequest, BatchRunResponse, CancelRunResponse, CliAgentRunParams, CliBrowserSessionCreateParams, CliFetchGetContentsParams, CookieRecord, ProfileCreateResponse, ProfileUploadResponse, RunStepsResponse, VaultConnectRequest, VaultConnectResponse, VaultConnectionsListResponse, VaultDisconnectResponse, VaultItemsListResponse, VaultItemsSyncResponse } from './types.js';
+import { z } from 'zod';
 type ConnectMap = Record<string, {
     attempt_id: string;
 }> | undefined;
@@ -12,7 +13,116 @@ export declare function listRuns(opts: RunListParams, apiKey: string, timeout?:
 export declare function getRun(runId: string, apiKey: string): Promise<Run>;
 export declare function getRunSteps(runId: string, apiKey: string): Promise<RunStepsResponse>;
 export declare function searchQuery(params: SearchQueryParams, apiKey: string): Promise<SearchQueryResponse>;
-export declare function fetchContentGet(params: FetchGetContentsParams, apiKey: string): Promise<FetchResponse>;
+declare const cliFetchResponseSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodIntersection<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        url: z.ZodString;
+        final_url: z.ZodNullable<z.ZodString>;
+        title: z.ZodNullable<z.ZodString>;
+        description: z.ZodNullable<z.ZodString>;
+        language: z.ZodNullable<z.ZodString>;
+        author: z.ZodNullable<z.ZodString>;
+        published_date: z.ZodNullable<z.ZodString>;
+        links: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        image_links: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        latency_ms: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        not_modified: z.ZodOptional<z.ZodBoolean>;
+        etag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        last_modified: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        format: z.ZodLiteral<"markdown">;
+        text: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        url: z.ZodString;
+        final_url: z.ZodNullable<z.ZodString>;
+        title: z.ZodNullable<z.ZodString>;
+        description: z.ZodNullable<z.ZodString>;
+        language: z.ZodNullable<z.ZodString>;
+        author: z.ZodNullable<z.ZodString>;
+        published_date: z.ZodNullable<z.ZodString>;
+        links: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        image_links: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        latency_ms: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        not_modified: z.ZodOptional<z.ZodBoolean>;
+        etag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        last_modified: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        format: z.ZodLiteral<"html">;
+        text: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        url: z.ZodString;
+        final_url: z.ZodNullable<z.ZodString>;
+        title: z.ZodNullable<z.ZodString>;
+        description: z.ZodNullable<z.ZodString>;
+        language: z.ZodNullable<z.ZodString>;
+        author: z.ZodNullable<z.ZodString>;
+        published_date: z.ZodNullable<z.ZodString>;
+        links: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        image_links: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        latency_ms: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        not_modified: z.ZodOptional<z.ZodBoolean>;
+        etag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        last_modified: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        format: z.ZodLiteral<"json">;
+        text: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodType<string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | /*elided*/ any | null;
+        } | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null, unknown, z.core.$ZodTypeInternals<string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | (string | number | boolean | /*elided*/ any | /*elided*/ any | null)[] | null;
+        } | (string | number | boolean | {
+            [key: string]: string | number | boolean | /*elided*/ any | /*elided*/ any | null;
+        } | /*elided*/ any | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null)[] | null, unknown>>>>;
+    }, z.core.$strip>], "format">, z.ZodObject<{
+        highlights: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            rank: z.ZodNumber;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>>;
+    errors: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        error: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CliFetchResponse = z.infer<typeof cliFetchResponseSchema>;
+export declare function fetchContentGet(params: CliFetchGetContentsParams, apiKey: string): Promise<CliFetchResponse>;
 export declare function browserSessionCreate(params: CliBrowserSessionCreateParams, apiKey: string): Promise<BrowserSession>;
 export declare function cancelRun(runId: string, apiKey: string): Promise<CancelRunResponse>;
 export declare function getWallet(apiKey: string): Promise<WalletResponse>;

package/dist/lib/client.js

@@ -1,4 +1,4 @@
-import { APIStatusError, agentRunAsyncResponseSchema, agentRunResponseSchema, agentRunWithStreamingResponseSchema, fetchResponseSchema, browserSessionSchema, searchQueryResponseSchema, TinyFish, runSchema, runStatusSchema, } from '@tiny-fish/sdk';
+import { APIStatusError, agentRunAsyncResponseSchema, agentRunResponseSchema, agentRunWithStreamingResponseSchema, fetchErrorSchema, fetchResultSchema, browserSessionSchema, searchQueryResponseSchema, TinyFish, runSchema, runStatusSchema, } from '@tiny-fish/sdk';
 import { CONNECT_SOURCE, loadConfig } from './auth.js';
 import { API_URL_OVERRIDE, CLI_AGENT_IDENTITY, CLI_VERSION } from './constants.js';
 import { detectHarness, detectHumanInitiated } from './harness.js';
@@ -281,10 +281,21 @@ export function searchQuery(params, apiKey) {
         return searchQueryResponseSchema.parse(response);
     });
 }
+const highlightSnippetSchema = z.object({
+    text: z.string(),
+    rank: z.number().int().min(1),
+});
+// Published SDK result schema strips `highlights`; intersect to keep it.
+// nullish, not optional: a null must not fail the whole response parse.
+const cliFetchResponseSchema = z.object({
+    results: z.array(z.intersection(fetchResultSchema, z.object({ highlights: z.array(highlightSnippetSchema).nullish() }))),
+    errors: z.array(fetchErrorSchema),
+});
 export function fetchContentGet(params, apiKey) {
     return sdk(apiKey, async (client) => {
-        const response = await client.fetch.getContents(params);
-        return fetchResponseSchema.parse(response);
+        // TODO(PROD-4260): use client.fetch.getContents once #4786 lands in an SDK release.
+        const response = await client.post(client.productUrl('fetch'), { json: params });
+        return parseWithSchema(cliFetchResponseSchema, response, 'Invalid fetch response');
     });
 }
 export function browserSessionCreate(params, apiKey) {

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

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

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

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

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

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