feat: connection health checks and identity

A connection can declare one authenticated operation that answers two
questions at once: is this credential still alive, and (optionally) whose
account is it? Built for the Google 7-day dev-OAuth case.

- Shared health-check vocabulary in core (spec/candidate/result, status
  classification, identity extraction, response-field projection) and the
  plugin hooks + dispatch wiring.
- OpenAPI implementation: ranked candidate listing, response-field projection
  (union-aware, breadth-first), a searchable operation picker, a typed identity
  picker, a live preview that shows the real response, and key-first connect.
- Per-connection status dot + Check now; no token-expiry timing shown (it
  refreshes), so status comes only from a live probe.

Author: RhysSullivan

e2e/scenarios/health-checks-ui.test.ts

@@ -16,6 +16,8 @@ import {
   ConnectionName,
   ConnectionNotFoundError,
   CredentialProviderNotRegisteredError,
+  HealthCheckResult,
+  HealthCheckSpec,
   IntegrationNotFoundError,
   IntegrationSlug,
   InternalError,
@@ -108,6 +110,31 @@ const CreateConnectionPayload = Schema.Struct({
   ),
 );
 
+// Validate an in-flight credential WITHOUT saving it (the key-first connect
+// flow). Same origin shape as create, plus an optional `spec` override so the
+// editor can preview a candidate against a live key. No `name` — the point is
+// to derive one from the identity the probe returns.
+const ValidateConnectionPayload = Schema.Struct({
+  owner: Owner,
+  integration: IntegrationSlug,
+  template: AuthTemplateSlug,
+  spec: Schema.optional(HealthCheckSpec),
+  value: Schema.optional(Schema.String),
+  values: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  from: Schema.optional(
+    Schema.Struct({
+      provider: ProviderKey,
+      id: ProviderItemId,
+    }),
+  ),
+}).check(
+  Schema.makeFilter((payload) =>
+    [payload.value, payload.values, payload.from].filter(Predicate.isNotUndefined).length === 1
+      ? undefined
+      : "Expected exactly one credential origin",
+  ),
+);
+
 // ---------------------------------------------------------------------------
 // Query — optional list filters.
 // ---------------------------------------------------------------------------
@@ -186,4 +213,25 @@ export const ConnectionsApi = HttpApiGroup.make("connections")
       success: Schema.Array(ToolResponse),
       error: [InternalError, ConnectionNotFound, IntegrationNotFound],
     }),
+  )
+  // Run the integration's declared health check against a SAVED connection: is
+  // this credential still alive (Google's 7-day dev-token revocation), and whose
+  // account is it? Returns a classified status + optional identity, never an
+  // error for an auth wall (that surfaces as `status: "expired"`).
+  .add(
+    HttpApiEndpoint.post("checkHealth", "/connections/:owner/:integration/:name/health", {
+      params: ConnectionParams,
+      success: HealthCheckResult,
+      error: [InternalError, ConnectionNotFound, IntegrationNotFound],
+    }),
+  )
+  // Run the health check against an IN-FLIGHT credential without saving it (the
+  // key-first connect flow): confirm the pasted key works and surface the
+  // identity the UI derives a connection name from before anything persists.
+  .add(
+    HttpApiEndpoint.post("validate", "/connections/validate", {
+      payload: ValidateConnectionPayload,
+      success: HealthCheckResult,
+      error: [InternalError, IntegrationNotFound],
+    }),
   );

e2e/scenarios/health-checks.test.ts

@@ -7,7 +7,9 @@ import {
   type Connection,
   type ConnectionRef,
   type CreateConnectionInput,
+  type HealthCheckResult,
   type Tool,
+  type ValidateConnectionInput,
 } from "@executor-js/sdk";
 
 import { ExecutorApi } from "../api";
@@ -38,6 +40,15 @@ const toolToResponse = (t: Tool) => ({
   description: t.description,
 });
 
+const toHealthResponse = (r: HealthCheckResult) => ({
+  status: r.status,
+  checkedAt: r.checkedAt,
+  ...(r.httpStatus !== undefined ? { httpStatus: r.httpStatus } : {}),
+  ...(r.identity !== undefined ? { identity: r.identity } : {}),
+  ...(r.detail !== undefined ? { detail: r.detail } : {}),
+  ...(r.responseSample !== undefined ? { responseSample: r.responseSample } : {}),
+});
+
 export const ConnectionsHandlers = HttpApiBuilder.group(ExecutorApi, "connections", (handlers) =>
   handlers
     .handle("list", ({ query }) =>
@@ -130,5 +141,30 @@ export const ConnectionsHandlers = HttpApiBuilder.group(ExecutorApi, "connection
           return tools.map(toolToResponse);
         }),
       ),
+    )
+    .handle("checkHealth", ({ params: path }) =>
+      capture(
+        Effect.gen(function* () {
+          const executor = yield* ExecutorService;
+          const result = yield* executor.connections.checkHealth({
+            owner: path.owner,
+            integration: path.integration,
+            name: path.name,
+          });
+          return toHealthResponse(result);
+        }),
+      ),
+    )
+    .handle("validate", ({ payload }) =>
+      capture(
+        Effect.gen(function* () {
+          const executor = yield* ExecutorService;
+          // The payload mirrors `ValidateConnectionInput`: owner/integration/
+          // template/spec plus a single credential origin (`value` | `values` |
+          // `from`). Pass it through verbatim.
+          const result = yield* executor.connections.validate(payload as ValidateConnectionInput);
+          return toHealthResponse(result);
+        }),
+      ),
     ),
 );

packages/core/api/src/connections/api.ts

@@ -79,5 +79,30 @@ export const IntegrationsHandlers = HttpApiBuilder.group(ExecutorApi, "integrati
           }));
         }),
       ),
+    )
+    .handle("healthCheckGet", ({ params: path }) =>
+      capture(
+        Effect.gen(function* () {
+          const executor = yield* ExecutorService;
+          return yield* executor.integrations.healthCheck.get(path.slug);
+        }),
+      ),
+    )
+    .handle("healthCheckCandidates", ({ params: path }) =>
+      capture(
+        Effect.gen(function* () {
+          const executor = yield* ExecutorService;
+          return yield* executor.integrations.healthCheck.candidates(path.slug);
+        }),
+      ),
+    )
+    .handle("healthCheckSet", ({ params: path, payload }) =>
+      capture(
+        Effect.gen(function* () {
+          const executor = yield* ExecutorService;
+          yield* executor.integrations.healthCheck.set(path.slug, payload.spec);
+          return { ok: true };
+        }),
+      ),
     ),
 );

packages/core/api/src/handlers/connections.ts

@@ -11,6 +11,8 @@
 import { HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
 import { Schema } from "effect";
 import {
+  HealthCheckCandidate,
+  HealthCheckSpec,
   IntegrationDetectionResult,
   IntegrationNotFoundError,
   IntegrationRemovalNotAllowedError,
@@ -88,6 +90,12 @@ const DetectRequest = Schema.Struct({
   url: Schema.String.check(Schema.isMaxLength(2_048)),
 });
 
+// Set (or clear, with null) the integration's declared health check. The spec
+// lives inside the owning plugin's opaque config; core only routes it.
+const SetHealthCheckPayload = Schema.Struct({
+  spec: Schema.NullOr(HealthCheckSpec),
+});
+
 // ---------------------------------------------------------------------------
 // Error schemas with HTTP status annotations
 // ---------------------------------------------------------------------------
@@ -136,4 +144,30 @@ export const IntegrationsApi = HttpApiGroup.make("integrations")
       success: Schema.Array(IntegrationDetectionResult),
       error: InternalError,
     }),
+  )
+  // The integration's currently declared health check (null when none is set).
+  .add(
+    HttpApiEndpoint.get("healthCheckGet", "/integrations/:slug/health-check", {
+      params: IntegrationParams,
+      success: Schema.NullOr(HealthCheckSpec),
+      error: InternalError,
+    }),
+  )
+  // Operations the user can pick as the health check, ranked non-destructive +
+  // fewest-required-args first so the obvious identity endpoint floats to the top.
+  .add(
+    HttpApiEndpoint.get("healthCheckCandidates", "/integrations/:slug/health-check/candidates", {
+      params: IntegrationParams,
+      success: Schema.Array(HealthCheckCandidate),
+      error: [InternalError, IntegrationNotFound],
+    }),
+  )
+  // Persist (or clear) the integration's health check.
+  .add(
+    HttpApiEndpoint.put("healthCheckSet", "/integrations/:slug/health-check", {
+      params: IntegrationParams,
+      payload: SetHealthCheckPayload,
+      success: Schema.Struct({ ok: Schema.Boolean }),
+      error: [InternalError, IntegrationNotFound],
+    }),
   );

packages/core/api/src/handlers/integrations.ts

@@ -8,6 +8,7 @@ import type {
   ProviderItemId,
   ProviderKey,
 } from "./ids";
+import type { HealthCheckSpec } from "./health-check";
 
 /* A Connection is THE saved credential — secret, account, and connection are one
  * concept — bound to exactly ONE integration (born wired; there is no unwired
@@ -95,6 +96,19 @@ export type CreateConnectionInput = {
   readonly description?: string | null;
 } & ConnectionValueInput;
 
+/** Validate an in-flight credential WITHOUT saving it (the key-first connect
+ *  flow). Resolves the pasted value(s) the same way `create` would, then runs
+ *  the integration's declared health check so the UI can confirm the key works
+ *  and derive a connection name from the returned identity before anything is
+ *  persisted. `spec` overrides the integration's declared check (used by the
+ *  editor to preview a candidate against a live key). */
+export type ValidateConnectionInput = {
+  readonly owner: Owner;
+  readonly integration: IntegrationSlug;
+  readonly template: AuthTemplateSlug;
+  readonly spec?: HealthCheckSpec;
+} & ConnectionValueInput;
+
 /** Edit a connection's user-curated metadata. Only the provided fields change;
  *  credentials and OAuth lifecycle are untouchable here (recreate or refresh
  *  instead). */