@zackbart/connecta 0.7.9 → 0.8.1

package/src/version.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.7.9";
+export const CONNECTA_VERSION = "0.8.1";

package/dist/credential-health.d.ts

@@ -1,227 +0,0 @@
-import type { CredentialVault } from "./credentials.js";
-import { type DeferredWork } from "./connector-scope.js";
-import type { Connector, ConnectorContext, ConnectorStatusState, KVStorage, Logger } from "./types.js";
-/** Verdict of one liveness check. Same vocabulary as `ConnectorStatus.state`. */
-export type CredentialCheckState = ConnectorStatusState;
-/** The stored verdict of the most recent liveness check of one connector. */
-export interface CredentialHealthRecord {
-    state: CredentialCheckState;
-    /** ISO timestamp of the check that produced this record. */
-    checkedAt: string;
-    /** Why, for a non-ok state — the connector's own reason, verbatim. */
-    message?: string;
-    /** Consent URL to open, when the connector reported one. */
-    authorizationUrl?: string;
-}
-/**
- * Why a connector was not checked.
- *
- * - `not_found` — no connector with that id is registered. Only reachable
- *   through an explicit `ids` request, and reported rather than dropped so a
- *   typo in a scheduled check is visible instead of silent.
- * - `not_checkable` — it stores no credential connecta manages, or exposes no
- *   usable way to ask: neither `status()` nor a credential test hook the
- *   declared credential shape can use (`credentialTestRule`), against a value
- *   actually stored under it.
- * - `no_credential` — checkable, but nothing is stored yet: there is no
- *   credential whose liveness could be in question, and probing would start an
- *   OAuth flow nobody asked for.
- * - `fresh` — checked less than `intervalSeconds` ago (by any isolate — the
- *   record is persisted), so this is the rate limit doing its job.
- * - `in_flight` — another check of this connector is already running.
- */
-export type CredentialCheckSkip = "not_found" | "not_checkable" | "no_credential" | "fresh" | "in_flight";
-/** One connector's outcome in a sweep. */
-export interface CredentialCheckResult {
-    connectorId: string;
-    /**
-     * The record now in force. Present for a completed check, and for a `fresh`
-     * skip (where the still-valid record is what the skip deferred to).
-     */
-    record?: CredentialHealthRecord;
-    /** Set when no check ran; `record` is then whatever was already stored. */
-    skipped?: CredentialCheckSkip;
-    /**
-     * The check ran, but its verdict was thrown away: the credential it judged
-     * was replaced or removed while it was in flight (see `clear`). `record` is
-     * what the check saw, not what is stored — nothing is.
-     */
-    discarded?: true;
-    /** How long the check took, when one ran. */
-    latencyMs?: number;
-}
-/** Deployment-wide tuning for credential liveness checks. */
-export interface CredentialHealthConfig {
-    /**
-     * Minimum seconds between checks of the same connector, across isolates (the
-     * verdict is persisted, so a Worker cron isolate and a request isolate share
-     * one clock). Default 900 (15 minutes). This is the bound on downstream cost:
-     * repeated status reads never each trigger a check.
-     */
-    intervalSeconds?: number;
-    /** Max checks in flight at once during one sweep. Default 4. */
-    concurrency?: number;
-    /** Per-check deadline. Default 30 000, the probe default. */
-    timeoutMs?: number;
-    /**
-     * Let inbound authenticated `/mcp` and `/ui/data` traffic trigger a *due*
-     * sweep in the background (`ctx.waitUntil` where the runtime has it). Default
-     * true — it is the trigger that makes stale-credential detection work with no
-     * scheduler wired at all, and it cannot slow a request down or change a
-     * result. Set false to check only from `Connecta.checkCredentials()`.
-     */
-    onRequest?: boolean;
-}
-export declare const DEFAULT_CREDENTIAL_CHECK_INTERVAL_SECONDS = 900;
-export declare const DEFAULT_CREDENTIAL_CHECK_CONCURRENCY = 4;
-/** What the checker needs from the registry, without depending on it. */
-export interface CredentialHealthDeps {
-    listConnectors(): Connector[];
-    getConnector(id: string): Connector | undefined;
-    contextFor(id: string, baseUrl: string, requestScope?: object): ConnectorContext;
-    storage: KVStorage;
-    logger: Logger;
-    credentialVault?: CredentialVault;
-}
-export interface CredentialCheckOptions {
-    /** Check even connectors whose verdict is still fresh. */
-    force?: boolean;
-    /** Restrict the sweep to these connector ids. Default: every connector. */
-    ids?: string[];
-    /**
-     * @deprecated Ignored. Credential checks always create and close their own
-     * probe scope; no core path supplies an existing request scope.
-     */
-    requestScope?: object;
-}
-/**
- * Whether a connector holds a credential connecta stores AND exposes a way to
- * ask whether it still works.
- *
- * Deliberately narrow. `listTools`/`callTool` are NOT liveness probes here: a
- * tool call may mutate downstream state, and the catalog path is already covered
- * by the existing probe. So a connector is checkable only through the two hooks
- * that exist to answer exactly this question — `testCredential(s)` (what the
- * Test button runs) and `status()` — and only when it has a credential of ours
- * to be asked about: an operator-managed `credential`, or a stored downstream
- * grant it reports via `hasStoredCredential`. A static-token connector stores
- * nothing here and is never probed on a timer.
- *
- * Whether a test hook counts is `credentialTestRule`'s call, not this function's
- * Credentials Test button and the credential API read (issue #55), so
- * a credential the operator cannot test by hand is not one a sweep tests behind
- * their back. A connector whose only hook cannot test its declared shape is
- * checkable only if it also implements `status()`.
- */
-export declare function isCheckableConnector(connector: Connector): boolean;
-/**
- * Runs and caches credential liveness checks. One instance per `Registry`.
- *
- * Cost is bounded four ways, because a status surface an agent polls must never
- * become a way to hammer a downstream auth endpoint:
- *
- * 1. **Eligibility** — only connectors holding a credential of ours are probed
- *    at all (`isCheckableConnector`), and only when something is actually stored.
- * 2. **Freshness (cross-isolate)** — a persisted verdict younger than
- *    `intervalSeconds` short-circuits the check, so every isolate and every
- *    trigger share one budget.
- * 3. **Sweep gate (per isolate)** — `sweepIfDue` runs at most one traffic-
- *    triggered sweep per interval per isolate, and never two at once, so a burst
- *    of requests costs one sweep, not one per request.
- * 4. **Deadline + fan-out bound** — each check is bounded by `timeoutMs` and at
- *    most `concurrency` run together (the same shape as the
- *    `discovery.probeTimeoutMs` bound on the discovery fan-out, issue #19).
- */
-export declare class CredentialHealthChecker {
-    private readonly deps;
-    private readonly store;
-    private readonly intervalMs;
-    private readonly concurrency;
-    private readonly timeoutMs;
-    private readonly onRequest;
-    /** Per-connector checks in flight in THIS isolate. */
-    private readonly inFlight;
-    /** Earliest a traffic-triggered sweep may run again in this isolate. */
-    private nextSweepAt;
-    private sweeping;
-    constructor(deps: CredentialHealthDeps, config?: CredentialHealthConfig);
-    /**
-     * The stored verdict, if any. No downstream I/O — and no storage read at all
-     * for a connector that stores no credential of ours, since only a checkable
-     * connector can ever have had a verdict written. That keeps
-     * `list_connectors({ probe: false })` exactly as cheap as it was for the
-     * deployments this feature does not apply to.
-     */
-    healthFor(connectorId: string): Promise<CredentialHealthRecord | undefined>;
-    /**
-     * Record a liveness verdict observed elsewhere — today, the live status a
-     * `list_connectors({ probe: true })` just performed. Filtered by the same
-     * eligibility rule as a check, so this stays a record of *credential* health
-     * rather than a general status cache, and so it also counts against the
-     * freshness budget: an operator who just probed live does not get swept again
-     * moments later.
-     */
-    record(connectorId: string, record: CredentialHealthRecord): Promise<void>;
-    /** Forget a connector's verdict — its credential just changed under us. */
-    clear(connectorId: string): Promise<void>;
-    /** Whether any connector in this deployment could be checked at all. */
-    hasCheckableConnectors(): boolean;
-    /**
-     * Check every (or the named) connector's stored credential and return one
-     * outcome per connector considered. Never rejects: a connector that throws,
-     * hangs past `timeoutMs`, or cannot be persisted becomes an `error` verdict.
-     */
-    check(baseUrl: string, opts?: CredentialCheckOptions, defer?: DeferredWork): Promise<CredentialCheckResult[]>;
-    /**
-     * The traffic-triggered sweep: a promise to hand to `ctx.waitUntil`, or
-     * `undefined` when nothing is due (the common case, and free — no I/O). The
-     * gate is armed BEFORE the sweep starts, so a burst of concurrent requests
-     * produces one sweep.
-     */
-    sweepIfDue(baseUrl: string, defer?: DeferredWork): Promise<CredentialCheckResult[]> | undefined;
-    private checkOne;
-    private recordOrNothing;
-    private runCheck;
-    /**
-     * `isCheckableConnector` re-asked against what is actually stored: the hook
-     * the declared shape selects, bound to a value that fits it (see
-     * {@link testHookFor}), or a `status()` to fall back on. Neither ⇒ there is no
-     * honest question to put to this connector.
-     */
-    private canAsk;
-    /**
-     * Ask the connector whether the credential it holds still works — with no
-     * downstream mutation and no tool call. A credential test is preferred for a
-     * vault credential because it validates the stored value itself; `status()` is
-     * the downstream-OAuth answer (it refreshes the grant, which is the liveness
-     * question for a token).
-     */
-    private probe;
-    private settle;
-}
-/**
- * Whether a liveness verdict may DECIDE a connector's cached status.
- *
- * Only `auth_required` ever does, and only while nothing better has happened
- * since. Two separate judgements:
- *
- * 1. **`error` is not credential evidence.** A check that timed out, threw, or
- *    got a 502 from the provider's status endpoint failed to *complete* — it
- *    learned nothing about the credential. Letting it set the status would flip
- *    a connector whose calls are fine to `error` for a whole interval on a DNS
- *    blip. Error verdicts stay visible in `credentialCheck` (an operator wants
- *    to know checks are failing) but the status keeps coming from observed real
- *    calls, which is evidence.
- * 2. **A successful real call retires the verdict, except static shape drift.**
- *    Traffic beats a background probe, so a `lastSuccessAt` at or after
- *    `checkedAt` normally means the credential demonstrably works. Stored-shape
- *    drift is different: a credential-independent tool can succeed without
- *    making a missing declared field appear, so only replacement/removal clears
- *    that verdict.
- *
- * `auth_required` deliberately outranks an observed real-call *failure*: both
- * say something is wrong, and only one of them carries the URL that fixes it.
- * The failure stays visible as `lastError`.
- */
-export declare function credentialVerdictApplies(record: CredentialHealthRecord | undefined, lastSuccessAt: string | undefined): boolean;
-//# sourceMappingURL=credential-health.d.ts.map

package/dist/credential-health.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"credential-health.d.ts","sourceRoot":"","sources":["../src/credential-health.ts"],"names":[],"mappings":"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"}