@tiny-fish/cli 0.12.1-next.139 → 0.12.1-next.143

package/README.md

@@ -263,7 +263,7 @@ tinyfish agent run "..." --url https://example.com --use-vault \
 
 By default all commands output newline-delimited JSON to stdout — pipe-friendly for agents and scripts. Add `--pretty` for human-readable output.
 
-Errors are JSON to stderr with exit code 1. Ctrl+C during a streaming run cancels it automatically.
+Errors are JSON to stderr with exit code 1. Ctrl+C during a streaming run cancels it automatically. The server may also attach an advisory upgrade notice to stderr: a plain line in a terminal, and JSON (`{"notice":…,"level":…}`) in non-interactive use. The JSON message is composed locally from the notice level, never from server-sent prose. It never changes stdout or the exit code.
 
 `--output-schema` and `--output-schema-file` are mutually exclusive. Both inputs must parse to a top-level JSON object. The CLI only validates that outer shape locally; the API performs full schema validation and may return errors such as `INVALID_INPUT` or feature-flag access failures.
 

package/dist/commands/connect.js

@@ -6,10 +6,10 @@ import { CLI_VERSION } from "../lib/constants.js";
 import { cursorInstallDeeplink, cursorMcpPath, writeCursorMcpConfig } from "../lib/cursor-config.js";
 import { runConnectAll } from "../lib/connect-all.js";
 import { detectHumanInitiated } from "../lib/harness.js";
+import { captureNotice, emitNotice } from "../lib/notice.js";
 import { errLine } from "../lib/output.js";
 import { telemetryDisabled, telemetryHeaders } from "../lib/setup-telemetry.js";
 import { verifyMcpAuth } from "../lib/verify.js";
-import { recordInstalledVersion } from "../lib/version-marker.js";
 export const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
 const SKILL_INSTALL_TIMEOUT_MS = 120_000;
@@ -254,6 +254,8 @@ function createConnectTelemetry(mcpUrl, client, apiKey) {
                     redirect: "error",
                     signal: AbortSignal.timeout(TELEMETRY_TIMEOUT_MS),
                 });
+                // Before the ok branch so an error response still yields a notice.
+                captureNotice(response.headers);
                 if (response.ok)
                     return;
                 if (response.status < 500) {
@@ -591,7 +593,6 @@ async function connectNativeMcpClient(client, options) {
         // Persist once here (skill installed + authenticated) so both success paths, launch
         // or not, record the install; buildConnectHeaders reads it on subsequent requests.
         saveConnectContext(client.connectClient, telemetry.attemptId);
-        recordInstalledVersion();
         errLine(UPGRADE_HINT);
         if (!options.launch) {
             errLine(`TinyFish is connected. Open ${client.displayName} to start using it.`);
@@ -662,7 +663,6 @@ export async function connectOpenClaw(options) {
         }
         telemetry.track("checkpoint", { phase: "authenticated" });
         saveConnectContext("openclaw", telemetry.attemptId);
-        recordInstalledVersion();
         errLine(UPGRADE_HINT);
         if (!options.launch) {
             errLine("TinyFish is connected. Open OpenClaw to start using it.");
@@ -706,7 +706,6 @@ export async function connectCursor(options) {
         }
         telemetry.track("checkpoint", { phase: "registered" });
         saveConnectContext("cursor", telemetry.attemptId);
-        recordInstalledVersion();
         if (resolvedKey) {
             // Deeplink would embed the key in a URL (process args, LaunchServices logs) — reload instead.
             const verify = await verifyMcpAuth(resolvedKey);
@@ -841,5 +840,7 @@ export function registerConnect(program) {
                 client +
                 ". Supported clients: claude-code, codex, cursor, hermes, openclaw");
         }
+        // Deferred to here so the notice lands after install output, not interleaved with it.
+        emitNotice();
     });
 }

package/dist/lib/connect-all.js

@@ -4,11 +4,11 @@ import { connectClaudeCode, connectCodex, connectCursor, connectHermes, connectO
 import { loadConfig, validateKeyFormat } from "./auth.js";
 import { detectInstalledHarnesses, FIVE_HARNESSES, } from "./harness-detect.js";
 import { detectHumanInitiated } from "./harness.js";
+import { emitNotice } from "./notice.js";
 import { removeCursorMcpServer, planCursorWrite } from "./cursor-config.js";
 import { errLine, outLine } from "./output.js";
 import { sendSetupCompleted } from "./setup-telemetry.js";
 import { verifyMcpAuth, verifyMcpHealth } from "./verify.js";
-import { printUpdateNoticeIfDrifted, recordInstalledVersion } from "./version-marker.js";
 const DISPLAY_NAMES = {
     "claude-code": "Claude Code",
     codex: "Codex",
@@ -153,7 +153,6 @@ async function processHarness(detection, opts, prompt) {
     if (!interruptedBefore && process.exitCode === 130) {
         return { ...base, outcome: "interrupted", fixCommand: `tinyfish connect ${harness}` };
     }
-    recordInstalledVersion();
     const verify = await verifyHarness(harness, opts.mcpUrl, resolvedApiKey(opts.apiKey));
     return {
         ...base,
@@ -292,7 +291,8 @@ export async function runConnectAll(opts) {
             verify_ok: r.verifyOk ?? null,
         }));
         await sendSetupCompleted(opts.mcpUrl, harnessTelemetry, resolvedApiKey(opts.apiKey));
-        await printUpdateNoticeIfDrifted();
+        // After the summary and before the launch, which is where the user is reading.
+        emitNotice();
     }
     const exitCode = computeExitCode(results);
     const interrupted = results.some((r) => r.outcome === "interrupted");

package/dist/lib/notice.d.ts

@@ -0,0 +1,8 @@
+/** Test-only: the capture slot and the once-per-invocation latch are module state. */
+export declare function resetNoticeState(): void;
+/** Records the first notice seen; printing is deferred so it lands at the end of a command. */
+export declare function captureNotice(headers: Headers): void;
+/** Advisory only, never changes stdout, the exit code, or control flow. */
+export declare function emitNotice(): void;
+/** For callers where the response is the end of the command, such as one-shot API calls. */
+export declare function surfaceNotice(headers: Headers): void;

package/dist/lib/notice.js

@@ -0,0 +1,53 @@
+// Surfaces the advisory X-TF-Notice header the server attaches to outdated clients (PF-3301).
+import { CLI_VERSION } from "./constants.js";
+import { detectHumanInitiated } from "./harness.js";
+import { err, errLine, sanitizeLine } from "./output.js";
+const NOTICE_HEADER = "x-tf-notice";
+const LEVEL_HEADER = "x-tf-notice-level";
+const MAX_LENGTH = 300;
+const VALID_LEVELS = new Set(["required", "recommended"]);
+let captured;
+let printed = false;
+/** Test-only: the capture slot and the once-per-invocation latch are module state. */
+export function resetNoticeState() {
+    captured = undefined;
+    printed = false;
+}
+/** Records the first notice seen; printing is deferred so it lands at the end of a command. */
+export function captureNotice(headers) {
+    if (captured)
+        return;
+    if (typeof headers?.get !== "function")
+        return;
+    const message = sanitizeLine(headers.get(NOTICE_HEADER) ?? "")
+        .trim()
+        .slice(0, MAX_LENGTH);
+    if (!message)
+        return;
+    const rawLevel = headers.get(LEVEL_HEADER)?.trim().toLowerCase();
+    // Spread rather than `level: undefined`, which exactOptionalPropertyTypes rejects.
+    captured = { message, ...(rawLevel && VALID_LEVELS.has(rawLevel) ? { level: rawLevel } : {}) };
+}
+/** Built here, not by the server, so nothing it sends can reach an agent's context as instructions. */
+function agentMessage(level) {
+    return level === "required"
+        ? `This TinyFish CLI (${CLI_VERSION}) is below the required minimum. Run: tinyfish upgrade`
+        : `A TinyFish CLI update is available (you have ${CLI_VERSION}). Run: tinyfish upgrade`;
+}
+/** Advisory only, never changes stdout, the exit code, or control flow. */
+export function emitNotice() {
+    if (printed || !captured)
+        return;
+    printed = true;
+    const { message, level } = captured;
+    if (detectHumanInitiated()) {
+        errLine(message);
+        return;
+    }
+    err({ notice: agentMessage(level), ...(level ? { level } : {}) });
+}
+/** For callers where the response is the end of the command, such as one-shot API calls. */
+export function surfaceNotice(headers) {
+    captureNotice(headers);
+    emitNotice();
+}

package/dist/lib/output.d.ts

@@ -4,6 +4,8 @@ export declare class ApiError extends Error {
     constructor(status: number, message: string, code?: string | undefined);
 }
 export declare function out(data: unknown): void;
+/** The only writer for untrusted text: strips ANSI and C0/C1 controls. */
+export declare function sanitizeLine(text: string): string;
 export declare function outLine(line: string): void;
 export declare function errLine(line: string): void;
 export declare function err(data: unknown): void;

package/dist/lib/output.js

@@ -12,20 +12,21 @@ export class ApiError extends Error {
 export function out(data) {
     process.stdout.write(JSON.stringify(data) + "\n");
 }
-function safe(text) {
+/** The only writer for untrusted text: strips ANSI and C0/C1 controls. */
+export function sanitizeLine(text) {
     // eslint-disable-next-line no-control-regex
     return stripVTControlCharacters(text).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
 }
 export function outLine(line) {
-    process.stdout.write(safe(line) + "\n");
+    process.stdout.write(sanitizeLine(line) + "\n");
 }
 export function errLine(line) {
-    process.stderr.write(safe(line) + "\n");
+    process.stderr.write(sanitizeLine(line) + "\n");
 }
 export function err(data) {
     const payload = typeof data === "string" ? { error: data } : data;
     const serialized = JSON.stringify(payload) ?? "undefined";
-    process.stderr.write(safe(serialized) + "\n");
+    process.stderr.write(sanitizeLine(serialized) + "\n");
 }
 export function handleApiError(e) {
     if (e instanceof ApiError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.12.1-next.139",
+  "version": "0.12.1-next.143",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {
@@ -32,7 +32,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@tiny-fish/sdk": "^0.2.0",
+    "@tiny-fish/sdk": "^0.3.0",
     "chrome-cookies-secure": "^3.0.2",
     "commander": "^12.0.0",
     "cross-spawn": "^7.0.6",
@@ -56,6 +56,7 @@
     "brace-expansion": "^5.0.9",
     "ip-address": ">=10.3.1",
     "postcss": ">=8.5.23",
+    "nanoid": "^3.3.17",
     "tar": "^7.5.21"
   },
   "engines": {

package/dist/lib/version-marker.d.ts

@@ -1,10 +0,0 @@
-/** Install-time, offline-safe; best-effort — never fails a finished install. */
-export declare function recordInstalledVersion(): void;
-interface UpdateCheckResult {
-    updateAvailable: boolean;
-    latest?: string;
-}
-/** Throttled npm-currency check; never auto-mutates the install. */
-export declare function checkForCliUpdate(now?: number): Promise<UpdateCheckResult>;
-export declare function printUpdateNoticeIfDrifted(): Promise<void>;
-export {};

package/dist/lib/version-marker.js

@@ -1,109 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import { z } from "zod";
-import { configDir } from "./auth.js";
-import { CLI_VERSION } from "./constants.js";
-import { errLine } from "./output.js";
-import { telemetryDisabled } from "./setup-telemetry.js";
-const MARKER_FILE = "skill-version-marker.json";
-const THROTTLE_MS = 24 * 60 * 60 * 1000;
-const CHECK_TIMEOUT_MS = 5_000;
-// npm is the only currency signal with a publisher behind it: the cookbook repo has no
-// releases and no release automation, so a tag check would report "up to date" forever.
-const REGISTRY_URL = "https://registry.npmjs.org/@tiny-fish/cli/latest";
-const markerSchema = z.object({
-    last_checked_at: z.number().optional(),
-    last_known_latest: z.string().optional(),
-});
-function markerPath() {
-    return path.join(configDir(), MARKER_FILE);
-}
-function readMarker() {
-    try {
-        const parsed = markerSchema.safeParse(JSON.parse(fs.readFileSync(markerPath(), "utf8")));
-        return parsed.success ? parsed.data : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-function writeMarker(state) {
-    fs.mkdirSync(configDir(), { recursive: true, mode: 0o700 });
-    const tmpPath = `${markerPath()}.tmp-${process.pid}`;
-    fs.writeFileSync(tmpPath, JSON.stringify(state), { mode: 0o600 });
-    fs.renameSync(tmpPath, markerPath());
-}
-/** Install-time, offline-safe; best-effort — never fails a finished install. */
-export function recordInstalledVersion() {
-    try {
-        writeMarker({ ...readMarker() });
-    }
-    catch {
-        // marker is a nice-to-have
-    }
-}
-const SEMVER = /^v?(\d+)\.(\d+)\.(\d+)$/;
-/** Strictly newer; false on unparsable input. */
-function isNewer(current, latest) {
-    const c = SEMVER.exec(current);
-    const l = SEMVER.exec(latest);
-    if (!c || !l)
-        return false;
-    for (let i = 1; i <= 3; i++) {
-        const cn = Number(c[i]);
-        const ln = Number(l[i]);
-        if (ln !== cn)
-            return ln > cn;
-    }
-    return false;
-}
-/** Throttled npm-currency check; never auto-mutates the install. */
-export async function checkForCliUpdate(now = Date.now()) {
-    const marker = readMarker();
-    // No marker means the CLI never installed anything — nothing to nag about.
-    if (!marker || telemetryDisabled())
-        return { updateAvailable: false };
-    const cached = () => ({
-        updateAvailable: marker.last_known_latest !== undefined && isNewer(CLI_VERSION, marker.last_known_latest),
-        ...(marker.last_known_latest !== undefined ? { latest: marker.last_known_latest } : {}),
-    });
-    // Time-based only — failed fetch must not stall every invocation.
-    if (marker.last_checked_at !== undefined && now - marker.last_checked_at < THROTTLE_MS) {
-        return cached();
-    }
-    let latest;
-    try {
-        const response = await fetch(REGISTRY_URL, {
-            headers: { accept: "application/json" },
-            signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
-        });
-        if (response.ok) {
-            const body = (await response.json());
-            if (typeof body.version === "string")
-                latest = body.version;
-        }
-    }
-    catch {
-        // Unreachable registry — don't fail setup, don't erase the cache.
-    }
-    try {
-        writeMarker({
-            ...marker,
-            last_checked_at: now,
-            last_known_latest: latest ?? marker.last_known_latest,
-        });
-    }
-    catch {
-        // best-effort
-    }
-    // Fall back to the cache so consecutive invocations can't disagree.
-    if (!latest)
-        return cached();
-    return { updateAvailable: isNewer(CLI_VERSION, latest), latest };
-}
-export async function printUpdateNoticeIfDrifted() {
-    const { updateAvailable } = await checkForCliUpdate();
-    if (updateAvailable) {
-        errLine("a newer TinyFish CLI is available — re-run `npx @tiny-fish/cli connect --all`");
-    }
-}