@tiny-fish/cli 0.38.1-next.303 → 0.38.1-next.305

package/dist/commands/connect.js

@@ -354,7 +354,10 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
                     apiKey: validatedApiKey(options.apiKey),
                     verbose: options.verbose ?? false,
                 });
-                telemetry.track('checkpoint', { phase: 'plugin_installed' });
+                telemetry.track('checkpoint', {
+                    phase: 'plugin_installed',
+                    pluginVersion: client.pluginVersion,
+                });
             });
         }
         // Before auth: a failed sign-in must not lose the harness record.

package/dist/commands/doctor.js

@@ -4,12 +4,12 @@ import { DOCTOR_COULD_NOT_RUN, DOCTOR_INVALID_INPUT, DOCTOR_SCHEMA_VERSION, doct
 import { applyRepairs, repairsFor } from '../lib/doctor-repairs.js';
 import { couldNotRunPayload, telemetryKey, telemetryPayload } from '../lib/doctor-telemetry.js';
 import { ALL_HARNESSES, AuthMode, Registered } from '../lib/harness-detect.js';
-import { err, errLine, out, outLine } from '../lib/output.js';
+import { boundedVersion, err, errLine, out, outLine } from '../lib/output.js';
 import { detectRegistrations } from '../lib/registration-detect.js';
 import { sendDoctorCompleted } from '../lib/setup-telemetry.js';
 import { verifyMcpAuth, verifyMcpHealth } from '../lib/verify.js';
 import { resolveHermesHome } from '../lib/hermes-env.js';
-import { hermesWebBackendsOurs, readHermesPluginStatus, } from '../lib/hermes-plugin.js';
+import { HERMES_PLUGIN_VERSION, hermesWebBackendsOurs, readHermesPluginStatus, } from '../lib/hermes-plugin.js';
 import { DEFAULT_MCP_URL, endpointOf, isDefaultEndpoint } from '../lib/mcp-endpoint.js';
 // A green auth mode with a red auth call proves nothing, so the call's verdict gates the claim.
 function provesHarnessReach(status, keyAuth, healthOk, mcpUrl) {
@@ -249,25 +249,42 @@ function hermesPluginVerdict(home) {
             detail: '`hermes tinyfish status --json` returned unparseable output',
         };
     }
-    return hermesPluginStatusVerdict(probe.status);
+    return {
+        ...hermesPluginStatusVerdict(probe.status),
+        // Machine-supplied, so it is bounded here rather than trusted onward.
+        observedVersion: boundedVersion(probe.status.plugin_version ?? ''),
+    };
 }
 function checkHermesPlugin(status) {
-    const check = {
+    const base = {
         id: 'hermes-plugin',
         title: 'Hermes web plugin',
         harness: 'hermes',
         scope: 'harness',
     };
-    if (!status.detected)
-        return { ...check, status: 'skip', detail: 'harness not installed' };
+    if (!status.detected) {
+        return { check: { ...base, status: 'skip', detail: 'harness not installed' } };
+    }
     if (status.registered !== Registered.Yes) {
-        return { ...check, status: 'skip', detail: 'TinyFish is not registered in Hermes' };
+        return { check: { ...base, status: 'skip', detail: 'TinyFish is not registered in Hermes' } };
     }
     const home = resolveHermesHome();
     if (!home) {
-        return { ...check, status: 'warn', detail: "could not determine Hermes' home directory" };
+        return {
+            check: { ...base, status: 'warn', detail: "could not determine Hermes' home directory" },
+        };
     }
-    return { ...check, ...hermesPluginVerdict(home) };
+    const { observedVersion, ...verdict } = hermesPluginVerdict(home);
+    return { check: { ...base, ...verdict }, observedVersion };
+}
+/** Skips mean no Hermes; stamping those buries the drift share. */
+function hermesPluginVersions(result) {
+    if (!result || result.check.status === 'skip')
+        return {};
+    return {
+        hermes_plugin_expected_version: HERMES_PLUGIN_VERSION,
+        ...(result.observedVersion ? { hermes_plugin_version: result.observedVersion } : {}),
+    };
 }
 export async function runDoctor(options) {
     const statuses = detectRegistrations(options.harness ? [options.harness] : undefined);
@@ -279,11 +296,12 @@ export async function runDoctor(options) {
         Promise.all(statuses.map((status) => verifyHarnessKey(status, cliAuth, options.mcpUrl))),
     ]);
     const hermesStatus = statuses.find((status) => status.harness === 'hermes');
+    const hermesPlugin = hermesStatus ? checkHermesPlugin(hermesStatus) : undefined;
     const checks = [
         checkCliVersion(),
         connectivity,
         ...statuses.map((status, i) => checkRegistration(status, options.mcpUrl, keyAuths[i], !credential.key)),
-        ...(hermesStatus ? [checkHermesPlugin(hermesStatus)] : []),
+        ...(hermesPlugin ? [hermesPlugin.check] : []),
         credential.check,
         checkAuthCall(cliAuthResult),
     ];
@@ -303,8 +321,9 @@ export async function runDoctor(options) {
         checks,
         harnesses,
         repairs: repairsFor(checks, statuses),
+        ...hermesPluginVersions(hermesPlugin),
     };
-    // Nothing to scrub: every string above is authored here or enumerated at its source.
+    // The one unauthored string is bounded before it lands here.
     return doctorReportSchema.parse(body);
 }
 export function registerDoctor(program) {

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

@@ -60,6 +60,8 @@ interface BaseMcpClient extends SupportedCommand, Pick<HarnessSpec, 'skillAgent'
         apiKey?: string;
         verbose: boolean;
     }) => void;
+    /** Pin `extraPostInstall` installs, reported on the plugin_installed checkpoint. */
+    pluginVersion?: string;
     /** Extra --uninstall row beyond `removals`; never runs pre-add. */
     uninstallExtra?: {
         args: string[];

package/dist/lib/connect-clients.js

@@ -8,7 +8,7 @@ import { TINYFISH_API_KEY_VAR } 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';
-import { installHermesPlugin, setHermesWebBackends } from './hermes-plugin.js';
+import { HERMES_PLUGIN_VERSION, installHermesPlugin, setHermesWebBackends, } from './hermes-plugin.js';
 const HERMES_SEED_TIMEOUT_MS = 120_000;
 const OPENCLAW_SKILL = '@tinyfish/tinyfish';
 // --force makes this an unconditional overwrite, so the same call installs and refreshes.
@@ -207,6 +207,7 @@ const HARNESS_OVERRIDES = {
     hermes: {
         launchWalkthrough: launchHermesWalkthrough,
         extraPostInstall: installHermesWebPlugin,
+        pluginVersion: HERMES_PLUGIN_VERSION,
         seedKey: seedHermesKey,
     },
     opencode: { launchWalkthrough: launchOpencode },
@@ -238,6 +239,7 @@ function toNativeClient(harness) {
         detachedLaunch: overrides.detachedLaunch,
         postConnectNote: spec.postConnectNote,
         extraPostInstall: overrides.extraPostInstall,
+        pluginVersion: overrides.pluginVersion,
         uninstallExtra: spec.uninstallExtra,
     };
     if (spec.keyRequired) {

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

@@ -66,6 +66,8 @@ interface ConnectStageDetail {
     phase?: ConnectCheckpoint;
     failureReason?: ConnectFailureReason;
     harnessVersion?: string;
+    /** The plugin the client pins, not a probe of what landed. */
+    pluginVersion?: string;
     authMode?: ConnectAuthMode;
     /** Orthogonal to `authMode`: a stored key wins over `mcp login` on a healthy client too. */
     harnessDegraded?: boolean;

package/dist/lib/connect-runtime.js

@@ -3,7 +3,7 @@ import spawn from 'cross-spawn';
 import { CONNECT_ATTEMPT_ENV, isAttemptId, resolvedApiKey, takePendingConnectAttempt, } from './auth.js';
 import { CLI_INVOCATION_ID, CLI_VERSION } from './constants.js';
 import { detectHarness, detectHumanInitiated, detectRuntimeEnv } from './harness.js';
-import { errLine, sanitizeLine } from './output.js';
+import { boundedVersion, errLine, sanitizeLine } from './output.js';
 import { postConnectEvent, telemetryDisabled } from './setup-telemetry.js';
 import { installSignalGuard } from './signals.js';
 export const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
@@ -232,12 +232,7 @@ function probeHarnessVersion(command) {
     });
     if (result.error || result.status !== 0)
         return undefined;
-    // First line only: sanitizeLine keeps newlines, so stripping splices lines.
-    const version = sanitizeLine(result.stdout ?? '')
-        .split('\n')[0]
-        .replace(/[^\x20-\x7E]/g, '')
-        .trim();
-    return version ? version.slice(0, 32) : undefined;
+    return boundedVersion(result.stdout ?? '');
 }
 /**
  * One page-minted id seeds one install attempt, so `tinyfish onboard` connecting three agents
@@ -294,6 +289,7 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
             // Terminal rows only: rescue checkpoints stay wire-identical to normal ones.
             fallback_outcome: stage === 'failed' || stage === 'aborted' ? fallbackOutcome : undefined,
             harness_version: detail?.harnessVersion ?? harnessVersion,
+            plugin_version: detail?.pluginVersion,
             auth_mode: detail?.authMode,
             harness_degraded: detail?.harnessDegraded,
             stage_duration_ms: stageDurationMs,

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

@@ -150,6 +150,8 @@ export declare const doctorReportSchema: z.ZodObject<{
         command: z.ZodString;
         unattended_safe: z.ZodBoolean;
     }, z.core.$strip>>;
+    hermes_plugin_version: z.ZodOptional<z.ZodString>;
+    hermes_plugin_expected_version: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type CheckStatus = z.infer<typeof checkStatusSchema>;
 export type CheckScope = z.infer<typeof checkScopeSchema>;

package/dist/lib/doctor-report.js

@@ -46,6 +46,9 @@ export const doctorReportSchema = z
     checks: z.array(doctorCheckSchema),
     harnesses: z.array(doctorHarnessSchema),
     repairs: z.array(doctorRepairSchema),
+    // Unbounded like cli_version: a throw here exits 2 unnecessarily.
+    hermes_plugin_version: z.string().optional(),
+    hermes_plugin_expected_version: z.string().optional(),
 })
     // Claiming ok while that scope failed is worse than no report.
     .refine((report) => !report.ok_harnesses || !hasFailure(report.checks, 'harness'), {

package/dist/lib/doctor-telemetry.js

@@ -38,6 +38,12 @@ export function telemetryPayload(report, offered, outcomes, options, durationMs)
         harnesses: report.harnesses,
         // Clamped, not validated: a --fix parked at a prompt must not fail the parse and drop the run.
         duration_ms: Math.min(durationMs, MAX_DURATION_MS),
+        ...(report.hermes_plugin_version
+            ? { hermes_plugin_version: report.hermes_plugin_version }
+            : {}),
+        ...(report.hermes_plugin_expected_version
+            ? { hermes_plugin_expected_version: report.hermes_plugin_expected_version }
+            : {}),
     };
 }
 /** Both paths send keyless when there is no key; the route records those anonymously. */

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { type InstallOptions } from './cli-install.js';
 export declare const HERMES_PLUGIN_SHA = "496cd63fefd982bbaa8a85ce78ef2270d700984f";
+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;
 /** After install only: backends must never name an absent provider. */

package/dist/lib/hermes-plugin.js

@@ -10,6 +10,8 @@ import { HARNESS_PROBE_TIMEOUT_MS } from './constants.js';
 import { errLine } from './output.js';
 // Bump per CLI release.
 export const HERMES_PLUGIN_SHA = '496cd63fefd982bbaa8a85ce78ef2270d700984f';
+// Bump with the SHA; the source is `hermes/plugin.yaml` at that commit.
+export const HERMES_PLUGIN_VERSION = '0.1.0';
 // Manifest `name:`, not the repo subdir; `plugins uninstall` keys on it.
 const PLUGIN_SOURCE = 'tinyfish-io/tinyfish-web-agent-integrations/hermes';
 const PLUGIN_REPO_URL = 'https://github.com/tinyfish-io/tinyfish-web-agent-integrations.git';

package/dist/lib/output.d.ts

@@ -6,6 +6,8 @@ export declare class ApiError extends Error {
 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;
+/** Every version the route caps at 32 printable ASCII chars. */
+export declare function boundedVersion(text: string): string | undefined;
 export declare function outLine(line: string): void;
 /** `connect --all` nests a harness's own lines under its step header. */
 export declare function setErrIndent(prefix: string): void;

package/dist/lib/output.js

@@ -17,6 +17,15 @@ export function sanitizeLine(text) {
     // eslint-disable-next-line no-control-regex
     return stripVTControlCharacters(text).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, '');
 }
+/** Every version the route caps at 32 printable ASCII chars. */
+export function boundedVersion(text) {
+    // First line only: sanitizeLine keeps newlines, so stripping splices lines.
+    const version = sanitizeLine(text)
+        .split('\n')[0]
+        .replace(/[^\x20-\x7E]/g, '')
+        .trim();
+    return version ? version.slice(0, 32) : undefined;
+}
 export function outLine(line) {
     process.stdout.write(sanitizeLine(line) + '\n');
 }

package/dist/lib/setup-telemetry.d.ts

@@ -160,6 +160,8 @@ export declare const doctorCompletedPayloadSchema: z.ZodObject<{
         proves_harness_reach: z.ZodBoolean;
     }, z.core.$strip>>;
     duration_ms: z.ZodInt;
+    hermes_plugin_version: z.ZodOptional<z.ZodString>;
+    hermes_plugin_expected_version: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const doctorCouldNotRunPayloadSchema: z.ZodObject<{
     outcome: z.ZodLiteral<"could_not_run">;
@@ -253,6 +255,8 @@ declare const doctorPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         proves_harness_reach: z.ZodBoolean;
     }, z.core.$strip>>;
     duration_ms: z.ZodInt;
+    hermes_plugin_version: z.ZodOptional<z.ZodString>;
+    hermes_plugin_expected_version: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     outcome: z.ZodLiteral<"could_not_run">;
     error_class: z.ZodEnum<{

package/dist/lib/setup-telemetry.js

@@ -211,8 +211,13 @@ export async function sendSetupCompleted(mcpUrl, harnesses, apiKey, mode, attemp
     await postConnectEvent({ endpoint, body, attempts: 2, label: 'setup', apiKey });
 }
 export const DOCTOR_HARNESS_SCOPES = ['all', ...ALL_HARNESSES];
-// Enumerated only: check ids, harness names and auth modes are authored here, so nothing
-// user-authored or credential-shaped can ride a doctor run to PostHog. `detail` never leaves.
+// Mirrors the route's cap; drops what the route would 400 un-retried.
+const versionSchema = z
+    .string()
+    .max(32)
+    .regex(/^[\x20-\x7E]*$/);
+// Ids, harnesses and auth modes are authored here; `detail` never leaves.
+// The plugin version is machine-supplied, sanitized before reaching this schema.
 // Caps mirror the route's schema: a payload the server would 400 is dropped here instead,
 // because postConnectEvent never retries a 4xx and the event would vanish silently.
 // Same spellings as cli_connect_stage.failure_reason; the type pins them.
@@ -264,6 +269,9 @@ export const doctorCompletedPayloadSchema = z.object({
     }))
         .max(16),
     duration_ms: z.int().nonnegative().max(3_600_000),
+    /** Bounded here, not on the report: a reject drops only telemetry. */
+    hermes_plugin_version: versionSchema.optional(),
+    hermes_plugin_expected_version: versionSchema.optional(),
 });
 // Detection threw, so there is no report to aggregate: enumerated outcome and timing only.
 export const doctorCouldNotRunPayloadSchema = z.object({

package/package.json

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