@graphrefly/graphrefly 0.45.0 → 0.46.0

package/README.md

@@ -14,8 +14,7 @@ GraphReFly is a reactive graph protocol for human + LLM co-operation. Code is th
 | Package | What it is |
 |---|---|
 | [`@graphrefly/graphrefly`](https://www.npmjs.com/package/@graphrefly/graphrefly) | The library — reactive graph primitives, operators, `Graph` container, framework adapters. |
-| [`@graphrefly/mcp-server`](./packages/mcp-server) | Model Context Protocol server — expose GraphReFly to Claude Desktop, Claude Code, Cline, Cursor, and any MCP client as `graphrefly_*` tools. |
-| [`@graphrefly/cli`](./packages/cli) | Stateless command-line shell — `describe`, `explain`, `observe`, `reduce`, `snapshot`, and `mcp` (boot the server) from your terminal or CI. |
+| [`@graphrefly/cli`](./packages/cli) | Stateless command-line shell — `describe`, `explain`, `observe`, `reduce`, `snapshot` from your terminal or CI. |
 
 ---
 

package/dist/_internal-B23BagFd.d.cts

@@ -0,0 +1,33 @@
+import { Node } from '@graphrefly/pure-ts/core';
+
+/**
+ * Internal helpers shared by resilience sub-files.
+ *
+ * Not part of the public surface. The base-layer resilience operators
+ * co-located here (`retry.ts`, `status.ts`, `timeout.ts`) import what they
+ * need from this file directly; the utils-layer resilience primitives that
+ * stayed in `utils/resilience/` (`breaker.ts`, `rate-limiter.ts`,
+ * `fallback.ts`) import it top-down via `../../base/resilience/_internal.js`.
+ *
+ * `NodeOrValue<T>` is the only export re-surfaced publicly — there is no
+ * `base/resilience/index.ts`; it ships through `utils/resilience/index.ts`
+ * (and `utils/memory/index.ts`). Every resilience primitive that accepts
+ * reactive options uses it as the option-arg shape.
+ */
+
+/**
+ * Either a literal value or a reactive Node carrying it. Mirrors
+ * {@link FallbackInput}'s precedent for "options that may be reactive."
+ *
+ * Used by {@link timeout} / {@link retry} / {@link rateLimiter} /
+ * {@link circuitBreaker} / {@link budgetGate} to accept reactive option
+ * configurations (Tier 6.5 3.2, 2026-04-29). Each primitive subscribes
+ * to the option Node via {@link resolveReactiveOption} and rebinds
+ * internal state per its locked swap-semantic rule (see each primitive's
+ * JSDoc for the rule).
+ *
+ * @category extra
+ */
+type NodeOrValue<T> = T | Node<T>;
+
+export type { NodeOrValue as N };

package/dist/_internal-B23BagFd.d.ts

@@ -0,0 +1,33 @@
+import { Node } from '@graphrefly/pure-ts/core';
+
+/**
+ * Internal helpers shared by resilience sub-files.
+ *
+ * Not part of the public surface. The base-layer resilience operators
+ * co-located here (`retry.ts`, `status.ts`, `timeout.ts`) import what they
+ * need from this file directly; the utils-layer resilience primitives that
+ * stayed in `utils/resilience/` (`breaker.ts`, `rate-limiter.ts`,
+ * `fallback.ts`) import it top-down via `../../base/resilience/_internal.js`.
+ *
+ * `NodeOrValue<T>` is the only export re-surfaced publicly — there is no
+ * `base/resilience/index.ts`; it ships through `utils/resilience/index.ts`
+ * (and `utils/memory/index.ts`). Every resilience primitive that accepts
+ * reactive options uses it as the option-arg shape.
+ */
+
+/**
+ * Either a literal value or a reactive Node carrying it. Mirrors
+ * {@link FallbackInput}'s precedent for "options that may be reactive."
+ *
+ * Used by {@link timeout} / {@link retry} / {@link rateLimiter} /
+ * {@link circuitBreaker} / {@link budgetGate} to accept reactive option
+ * configurations (Tier 6.5 3.2, 2026-04-29). Each primitive subscribes
+ * to the option Node via {@link resolveReactiveOption} and rebinds
+ * internal state per its locked swap-semantic rule (see each primitive's
+ * JSDoc for the rule).
+ *
+ * @category extra
+ */
+type NodeOrValue<T> = T | Node<T>;
+
+export type { NodeOrValue as N };

package/dist/adaptive-rate-limiter-Dch_xYIi.d.cts

@@ -0,0 +1,111 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { NodeInput } from '@graphrefly/pure-ts/extra';
+
+/**
+ * Adaptive rate limiter — reactive, live-tunable, 429-aware.
+ *
+ * Wraps two `tokenBucket` instances (requests, tokens) with:
+ *   - Reactive `rpm` / `tpm` knobs that can be re-tuned at runtime via `NodeInput<number>`.
+ *   - An adaptation signal input (`Node<RateLimitSignal>`) that feeds back
+ *     provider 429 / retry-after / x-ratelimit-* headers to tighten limits.
+ *   - A `clampCooldownMs` TTL on signal-induced caps so a transient 429 doesn't
+ *     permanently throttle — caps decay back to user-configured values after
+ *     the cooldown elapses.
+ *   - TPM-miss recovery: consumed RPM tokens are returned to the request
+ *     bucket when the TPM admit fails, via `TokenBucket.putBack`.
+ *   - Imperative `acquire()` for bridging to Promise-based call paths
+ *     (used by the `withRateLimiter` adapter middleware).
+ *
+ * **Timer policy:** sleeps use `ResettableTimer` (documented spec §5.10
+ * escape hatch in `src/extra/timer.ts`) rather than `fromTimer` to avoid
+ * allocating a new Node per acquire cycle.
+ *
+ * Design lives in `docs/optimizations.md` § "Reactive adaptive rate limiter".
+ */
+
+/**
+ * Rate-limit signal emitted by an adaptation source (e.g., an HTTP 429 parser).
+ *
+ * Any subset of fields may be present. The adaptive rate limiter uses:
+ * - `retryAfterMs` — blocks acquire() for this duration.
+ * - `rpmCap` / `tpmCap` — tightens effective rpm/tpm to this value (decays
+ *   back to the user-configured cap after `clampCooldownMs`).
+ * - `usageHint` — updates the last-known rpm/tpm usage ratio for logging.
+ */
+interface RateLimitSignal {
+    /** Throttle duration — pause acquire() for this long. */
+    retryAfterMs?: number;
+    /** Hard cap for requests-per-minute; effective rpm = min(current, rpmCap) while clamp is active. */
+    rpmCap?: number;
+    /** Hard cap for tokens-per-minute; effective tpm = min(current, tpmCap) while clamp is active. */
+    tpmCap?: number;
+    /** Observed usage-percentage hint (0..1) — for observability, not gating. */
+    usageHint?: {
+        rpm?: number;
+        tpm?: number;
+    };
+    /** Free-form provider-specific payload. */
+    metadata?: Record<string, unknown>;
+}
+interface AdaptiveRateLimiterOptions {
+    name?: string;
+    /** Effective requests-per-minute cap. Reactive — reads push-on-subscribe. */
+    rpm?: NodeInput<number>;
+    /** Effective tokens-per-minute cap. Reactive. */
+    tpm?: NodeInput<number>;
+    /** Source of adaptation signals (429 parser output, etc.). */
+    adaptation?: NodeInput<RateLimitSignal>;
+    /**
+     * How long (ms) a signal-induced `rpmCap` / `tpmCap` stays in effect before
+     * relaxing back to the user-configured value. Default 60_000 (one minute).
+     * Set to `Infinity` to make signal caps sticky until manually cleared.
+     * A fresh signal with the same cap resets the cooldown.
+     */
+    clampCooldownMs?: number;
+    /** Burst capacity overshoot above the steady-state rpm/tpm. Default 1 (no burst). */
+    burstMultiplier?: number;
+}
+interface AdaptiveRateLimiterBundle {
+    /** Effective requests-per-minute (post-signal-clamp). Reactive. */
+    readonly effectiveRpm: Node<number>;
+    /** Effective tokens-per-minute (post-signal-clamp). Reactive. */
+    readonly effectiveTpm: Node<number>;
+    /** Last adaptation signal observed. */
+    readonly lastSignal: Node<RateLimitSignal>;
+    /** Pending `acquire()` callers waiting for capacity. */
+    readonly pending: Node<number>;
+    /** Current request-token-bucket fill (approximate). */
+    readonly rpmAvailable: Node<number>;
+    /** Current token-bucket fill (approximate). */
+    readonly tpmAvailable: Node<number>;
+    /**
+     * Imperative bridge: wait until `requestCost` request-tokens and
+     * `tokenCost` tokens are available, then consume them. Honors the
+     * most recent `retryAfterMs` from adaptation signals. Rejects with
+     * an `AbortError`-named error if `signal` aborts while waiting.
+     * `requestCost` defaults to 1; `tokenCost` defaults to 0 (rpm-only gating).
+     */
+    acquire(opts?: {
+        requestCost?: number;
+        tokenCost?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Feed back observed token usage (post-call) so the TPM bucket reflects
+     * real consumption rather than the pre-call estimate. A positive `delta`
+     * debits additional TPM (undershot estimate); a negative `delta` credits
+     * back overshoot (`putBack`).
+     */
+    recordUsage(delta: number): void;
+    /** Manually feed an adaptation signal — useful for tests. */
+    recordSignal(sig: RateLimitSignal): void;
+    /** Dispose internal subscriptions and pending timers. */
+    dispose(): void;
+}
+/**
+ * Create an adaptive rate limiter. Compose with any call source via
+ * `await limiter.acquire({ requestCost, tokenCost, signal })`.
+ */
+declare function adaptiveRateLimiter(opts?: AdaptiveRateLimiterOptions): AdaptiveRateLimiterBundle;
+
+export { type AdaptiveRateLimiterBundle as A, type RateLimitSignal as R, type AdaptiveRateLimiterOptions as a, adaptiveRateLimiter as b };

package/dist/adaptive-rate-limiter-Dch_xYIi.d.ts

@@ -0,0 +1,111 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { NodeInput } from '@graphrefly/pure-ts/extra';
+
+/**
+ * Adaptive rate limiter — reactive, live-tunable, 429-aware.
+ *
+ * Wraps two `tokenBucket` instances (requests, tokens) with:
+ *   - Reactive `rpm` / `tpm` knobs that can be re-tuned at runtime via `NodeInput<number>`.
+ *   - An adaptation signal input (`Node<RateLimitSignal>`) that feeds back
+ *     provider 429 / retry-after / x-ratelimit-* headers to tighten limits.
+ *   - A `clampCooldownMs` TTL on signal-induced caps so a transient 429 doesn't
+ *     permanently throttle — caps decay back to user-configured values after
+ *     the cooldown elapses.
+ *   - TPM-miss recovery: consumed RPM tokens are returned to the request
+ *     bucket when the TPM admit fails, via `TokenBucket.putBack`.
+ *   - Imperative `acquire()` for bridging to Promise-based call paths
+ *     (used by the `withRateLimiter` adapter middleware).
+ *
+ * **Timer policy:** sleeps use `ResettableTimer` (documented spec §5.10
+ * escape hatch in `src/extra/timer.ts`) rather than `fromTimer` to avoid
+ * allocating a new Node per acquire cycle.
+ *
+ * Design lives in `docs/optimizations.md` § "Reactive adaptive rate limiter".
+ */
+
+/**
+ * Rate-limit signal emitted by an adaptation source (e.g., an HTTP 429 parser).
+ *
+ * Any subset of fields may be present. The adaptive rate limiter uses:
+ * - `retryAfterMs` — blocks acquire() for this duration.
+ * - `rpmCap` / `tpmCap` — tightens effective rpm/tpm to this value (decays
+ *   back to the user-configured cap after `clampCooldownMs`).
+ * - `usageHint` — updates the last-known rpm/tpm usage ratio for logging.
+ */
+interface RateLimitSignal {
+    /** Throttle duration — pause acquire() for this long. */
+    retryAfterMs?: number;
+    /** Hard cap for requests-per-minute; effective rpm = min(current, rpmCap) while clamp is active. */
+    rpmCap?: number;
+    /** Hard cap for tokens-per-minute; effective tpm = min(current, tpmCap) while clamp is active. */
+    tpmCap?: number;
+    /** Observed usage-percentage hint (0..1) — for observability, not gating. */
+    usageHint?: {
+        rpm?: number;
+        tpm?: number;
+    };
+    /** Free-form provider-specific payload. */
+    metadata?: Record<string, unknown>;
+}
+interface AdaptiveRateLimiterOptions {
+    name?: string;
+    /** Effective requests-per-minute cap. Reactive — reads push-on-subscribe. */
+    rpm?: NodeInput<number>;
+    /** Effective tokens-per-minute cap. Reactive. */
+    tpm?: NodeInput<number>;
+    /** Source of adaptation signals (429 parser output, etc.). */
+    adaptation?: NodeInput<RateLimitSignal>;
+    /**
+     * How long (ms) a signal-induced `rpmCap` / `tpmCap` stays in effect before
+     * relaxing back to the user-configured value. Default 60_000 (one minute).
+     * Set to `Infinity` to make signal caps sticky until manually cleared.
+     * A fresh signal with the same cap resets the cooldown.
+     */
+    clampCooldownMs?: number;
+    /** Burst capacity overshoot above the steady-state rpm/tpm. Default 1 (no burst). */
+    burstMultiplier?: number;
+}
+interface AdaptiveRateLimiterBundle {
+    /** Effective requests-per-minute (post-signal-clamp). Reactive. */
+    readonly effectiveRpm: Node<number>;
+    /** Effective tokens-per-minute (post-signal-clamp). Reactive. */
+    readonly effectiveTpm: Node<number>;
+    /** Last adaptation signal observed. */
+    readonly lastSignal: Node<RateLimitSignal>;
+    /** Pending `acquire()` callers waiting for capacity. */
+    readonly pending: Node<number>;
+    /** Current request-token-bucket fill (approximate). */
+    readonly rpmAvailable: Node<number>;
+    /** Current token-bucket fill (approximate). */
+    readonly tpmAvailable: Node<number>;
+    /**
+     * Imperative bridge: wait until `requestCost` request-tokens and
+     * `tokenCost` tokens are available, then consume them. Honors the
+     * most recent `retryAfterMs` from adaptation signals. Rejects with
+     * an `AbortError`-named error if `signal` aborts while waiting.
+     * `requestCost` defaults to 1; `tokenCost` defaults to 0 (rpm-only gating).
+     */
+    acquire(opts?: {
+        requestCost?: number;
+        tokenCost?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Feed back observed token usage (post-call) so the TPM bucket reflects
+     * real consumption rather than the pre-call estimate. A positive `delta`
+     * debits additional TPM (undershot estimate); a negative `delta` credits
+     * back overshoot (`putBack`).
+     */
+    recordUsage(delta: number): void;
+    /** Manually feed an adaptation signal — useful for tests. */
+    recordSignal(sig: RateLimitSignal): void;
+    /** Dispose internal subscriptions and pending timers. */
+    dispose(): void;
+}
+/**
+ * Create an adaptive rate limiter. Compose with any call source via
+ * `await limiter.acquire({ requestCost, tokenCost, signal })`.
+ */
+declare function adaptiveRateLimiter(opts?: AdaptiveRateLimiterOptions): AdaptiveRateLimiterBundle;
+
+export { type AdaptiveRateLimiterBundle as A, type RateLimitSignal as R, type AdaptiveRateLimiterOptions as a, adaptiveRateLimiter as b };