@tiny-fish/cli 0.12.1-next.142 → 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,6 +6,7 @@ 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";
@@ -253,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) {
@@ -837,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,6 +4,7 @@ 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";
@@ -290,6 +291,8 @@ export async function runConnectAll(opts) {
             verify_ok: r.verifyOk ?? null,
         }));
         await sendSetupCompleted(opts.mcpUrl, harnessTelemetry, resolvedApiKey(opts.apiKey));
+        // 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.142",
+  "version": "0.12.1-next.143",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {