Function connectionCheckHealth

packages/core/sdk/src/executor.ts:2623–2693

(
      ref: ConnectionRef,
      options?: {
        /** Skip the probe and return the persisted verdict when it is younger
         *  than this. The server owns the freshness decision so N open tabs
         *  revalidating on load cannot stampede an upstream. Omit = always
         *  probe (the manual "Check now"). */
        readonly ifStaleMs?: number;
      },
    )

      });

    const connectionCheckHealth = (
      ref: ConnectionRef,
      options?: {
        /** Skip the probe and return the persisted verdict when it is younger
         *  than this. The server owns the freshness decision so N open tabs
         *  revalidating on load cannot stampede an upstream. Omit = always
         *  probe (the manual "Check now"). */
        readonly ifStaleMs?: number;
      },
    ): Effect.Effect<
      HealthCheckResult,
      ConnectionNotFoundError | IntegrationNotFoundError | StorageFailure
    > =>
      Effect.gen(function* () {
        const connectionRow = yield* findConnectionRow(ref);
        if (!connectionRow) {
          return yield* new ConnectionNotFoundError({
            owner: ref.owner,
            integration: ref.integration,
            name: ref.name,
          });
        }
        if (options?.ifStaleMs !== undefined) {
          const cached = Option.getOrNull(decodeLastHealth(connectionRow.last_health));
          if (cached && Date.now() - cached.checkedAt < options.ifStaleMs) return cached;
        }
        const integrationRow = yield* findIntegrationRow(ref.integration);
        if (!integrationRow) {
          return yield* new IntegrationNotFoundError({ slug: ref.integration });
        }
        const runtime = runtimes.get(integrationRow.plugin_id);
        const check = runtime?.plugin.checkHealth;
        if (!runtime || !check) return unknownHealth();

        const values = yield* foldResolutionFailure(resolveConnectionValues(connectionRow));
        const record = rowToIntegrationRecord(
          integrationRow,
          describeAuthMethodsForRow(integrationRow),
        );
        const credential: ToolInvocationCredential = {
          owner: connectionRow.owner as Owner,
          integration: ref.integration,
          connection: ConnectionName.make(connectionRow.name),
          template: AuthTemplateSlug.make(connectionRow.template),
          value: values[PRIMARY_INPUT_VARIABLE] ?? null,
          values,
          config: record.config,
        };
        // Core resolves the declared spec (its own column) and hands it to the
        // plugin; plugins no longer read it out of their config.
        const spec = describeHealthCheckForRow(integrationRow) ?? undefined;
        const result = yield* foldPluginFailure(
          check({ ctx: runtime.ctx, integration: record, credential, spec }),
          `Health check for connection "${ref.name}" failed.`,
        );
        // Persist the verdict on the connection row so the accounts list shows
        // alive/expired at a glance. Best-effort: a write failure must not turn
        // a successful probe into an error.