Function connectionCheckHealth

packages/core/sdk/src/executor.ts:5042–5207

(
      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,
          });
        }
        // A recorded invalid_grant is the AS's standing verdict on this grant
        // (the refresh path's gate, applied to probing): a probe can still
        // pass on the access token's remaining lifetime, and persisting that
        // "healthy" would hide the required reconnect until the token finally
        // lapses — with read-time revalidation then trusting the lie forever.
        // Serve the dead-grant verdict and probe nothing; this covers the
        // manual "Check now" too. Only the reconnect mint, which rewrites
        // `provider_state` wholesale, re-opens probing. Nothing is written:
        // a buried `expired` verdict (e.g. a failing tool sync landing after
        // the recorder) is already re-derived on every read through
        // `presentedLastHealth`, so plain row reads agree with what this
        // serves — and a repair write here could observe a pre-reconnect
        // dead grant, pass the verdict CAS inside one SQLite `updated_at`
        // second, and stamp the OLD grant's expired verdict onto the freshly
        // reconnected row.
        // The verdict this check replaces, for the flip attributes on the
        // span (`previous_status` / `changed`). Read once, before any path
        // can write, so every exit annotates against the same baseline.
        const previous = presentedLastHealth(connectionRow);
        const reauthState = oauthReauthRequiredFromProviderState(connectionRow.provider_state);
        if (reauthState !== null) {
          const result = deadGrantVerdict(reauthState, connectionRow);
          yield* annotateHealthVerdict("dead_grant", result, previous);
          return result;
        }
        if (options?.ifStaleMs !== undefined) {
          const cached = Option.getOrNull(decodeLastHealth(connectionRow.last_health));
          if (cached && Date.now() - cached.checkedAt < options.ifStaleMs) {
            yield* annotateHealthVerdict("cache", cached, previous);
            return cached;
          }
        }
        const integrationRow = yield* findIntegrationRow(ref.integration);
        if (!integrationRow) {
          return yield* new IntegrationNotFoundError({ slug: ref.integration });
        }