@reefclaw/connect 0.1.12 → 0.1.14

package/assets/plugin/ccxt/binance-public.d.ts

@@ -0,0 +1,34 @@
+import type { CcxtTicker, CcxtOHLCV } from '../types.js';
+import type { OrderBookDepth } from '../simulator/types.js';
+import type { PublicMarketDataApi } from './public-market-data-api.js';
+export declare class BinancePublicApi implements PublicMarketDataApi {
+    private exchange;
+    constructor();
+    /** Fetch raw CCXT ticker (includes funding rate, OI, info). Returns null on error. */
+    fetchTickerRaw(symbol: string): Promise<Record<string, any> | null>;
+    /** Fetch current ticker for a symbol. Returns null on error. */
+    fetchTicker(symbol: string): Promise<CcxtTicker | null>;
+    /** Fetch funding rate for a perpetual futures symbol. Returns null on error. */
+    fetchFundingRate(symbol: string): Promise<Record<string, any> | null>;
+    /** Fetch open interest for a perpetual futures symbol. Returns null on error. */
+    fetchOpenInterest(symbol: string): Promise<Record<string, any> | null>;
+    /** Fetch order book depth. Returns null on error. */
+    fetchOrderBook(symbol: string, limit?: number): Promise<OrderBookDepth | null>;
+    /** Fetch OHLCV candles. Returns null on error. */
+    fetchOHLCV(symbol: string, timeframe?: string, limit?: number): Promise<CcxtOHLCV[] | null>;
+    /** Probe Binance USD-M FUTURES reachability from this host — the readiness
+     *  gate's core signal. Calls the futures-explicit implicit method so it hits
+     *  `fapi.binance.com` (a bare `fetchTime()` on this instance resolves to spot
+     *  `api.binance.com`, since the public client doesn't set defaultType:'future').
+     *  HTTP 451 = Binance geo-restriction; the ban gate does NOT classify 451, so
+     *  we inspect the message here. Ban-gate compliant (assertNotBanned/noteSuccess/
+     *  noteBinanceError). Outcomes:
+     *   - 'reachable'   clean response (driftMs = serverTime − localTime)
+     *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
+     *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
+     *   - 'unreachable' network / DNS / timeout / other error */
+    probeReachability(): Promise<{
+        outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
+        driftMs: number | null;
+    }>;
+}

package/assets/plugin/ccxt/binance-public.js

@@ -0,0 +1,180 @@
+// Thin wrapper around CCXT for Binance public API endpoints.
+// No API keys required — only uses public market data.
+import { createRequire } from 'node:module';
+import { logger } from '../logger.js';
+import { assertNotBanned, noteBinanceError, noteSuccess, BinanceBannedError } from './binance-ban-gate.js';
+const TAG = 'binance-public';
+// Load ccxt via CJS require — OpenClaw's ESM loader gives wrong module shape
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let ccxtCjs;
+try {
+    const _require = createRequire(import.meta.url);
+    ccxtCjs = _require('ccxt');
+}
+catch {
+    // Fallback: try global require (available in OpenClaw's loader context)
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    ccxtCjs = require('ccxt');
+}
+export class BinancePublicApi {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    exchange;
+    constructor() {
+        const BinanceClass = ccxtCjs.binance ?? ccxtCjs.default?.binance;
+        if (!BinanceClass) {
+            throw new Error('CCXT binance class not found — check ccxt version');
+        }
+        this.exchange = new BinanceClass({
+            enableRateLimit: true,
+        });
+        logger.info(TAG, 'Binance public API initialized (no auth)');
+    }
+    /** Fetch raw CCXT ticker (includes funding rate, OI, info). Returns null on error. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchTickerRaw(symbol) {
+        try {
+            assertNotBanned('fetchTickerRaw');
+            const r = await this.exchange.fetchTicker(symbol);
+            noteSuccess();
+            return r;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchTickerRaw(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** Fetch current ticker for a symbol. Returns null on error. */
+    async fetchTicker(symbol) {
+        try {
+            assertNotBanned('fetchTicker');
+            const raw = await this.exchange.fetchTicker(symbol);
+            noteSuccess();
+            return {
+                symbol: raw.symbol,
+                last: raw.last ?? 0,
+                bid: raw.bid ?? 0,
+                ask: raw.ask ?? 0,
+                baseVolume: raw.baseVolume ?? 0,
+                quoteVolume: raw.quoteVolume ?? 0,
+                change: raw.change ?? 0,
+                percentage: raw.percentage ?? 0,
+                timestamp: raw.timestamp ?? Date.now(),
+                datetime: raw.datetime ?? new Date().toISOString(),
+            };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchTicker(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** Fetch funding rate for a perpetual futures symbol. Returns null on error. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchFundingRate(symbol) {
+        try {
+            assertNotBanned('fetchFundingRate');
+            const r = await this.exchange.fetchFundingRate(symbol);
+            noteSuccess();
+            return r;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchFundingRate(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** Fetch open interest for a perpetual futures symbol. Returns null on error. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async fetchOpenInterest(symbol) {
+        try {
+            assertNotBanned('fetchOpenInterest');
+            const r = await this.exchange.fetchOpenInterest(symbol);
+            noteSuccess();
+            return r;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchOpenInterest(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** Fetch order book depth. Returns null on error. */
+    async fetchOrderBook(symbol, limit = 20) {
+        try {
+            assertNotBanned('fetchOrderBook');
+            const raw = await this.exchange.fetchOrderBook(symbol, limit);
+            noteSuccess();
+            return {
+                bids: (raw.bids ?? []).map((l) => [l[0], l[1]]),
+                asks: (raw.asks ?? []).map((l) => [l[0], l[1]]),
+                timestamp: raw.timestamp ?? Date.now(),
+            };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchOrderBook(${symbol}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** Fetch OHLCV candles. Returns null on error. */
+    async fetchOHLCV(symbol, timeframe = '1h', limit = 100) {
+        try {
+            assertNotBanned('fetchOHLCV');
+            const raw = await this.exchange.fetchOHLCV(symbol, timeframe, undefined, limit);
+            noteSuccess();
+            // Validate each candle has 6 numeric values
+            const valid = [];
+            for (const candle of raw) {
+                if (candle.length >= 6 &&
+                    typeof candle[0] === 'number' &&
+                    typeof candle[1] === 'number' &&
+                    typeof candle[2] === 'number' &&
+                    typeof candle[3] === 'number' &&
+                    typeof candle[4] === 'number' &&
+                    typeof candle[5] === 'number') {
+                    valid.push(candle);
+                }
+            }
+            return valid;
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.error(TAG, `fetchOHLCV(${symbol}, ${timeframe}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /** Probe Binance USD-M FUTURES reachability from this host — the readiness
+     *  gate's core signal. Calls the futures-explicit implicit method so it hits
+     *  `fapi.binance.com` (a bare `fetchTime()` on this instance resolves to spot
+     *  `api.binance.com`, since the public client doesn't set defaultType:'future').
+     *  HTTP 451 = Binance geo-restriction; the ban gate does NOT classify 451, so
+     *  we inspect the message here. Ban-gate compliant (assertNotBanned/noteSuccess/
+     *  noteBinanceError). Outcomes:
+     *   - 'reachable'   clean response (driftMs = serverTime − localTime)
+     *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
+     *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
+     *   - 'unreachable' network / DNS / timeout / other error */
+    async probeReachability() {
+        try {
+            assertNotBanned('reachabilityProbe');
+            const r = await this.exchange.fapiPublicGetTime({});
+            noteSuccess();
+            const serverTime = Number(r?.serverTime);
+            const driftMs = Number.isFinite(serverTime) ? serverTime - Date.now() : null;
+            return { outcome: 'reachable', driftMs };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            if (err instanceof BinanceBannedError) {
+                // Gate paused us (418/429 backoff or weight pacer) — we didn't actually
+                // reach the host, so the result is UNKNOWN, not a reachability failure.
+                return { outcome: 'unknown', driftMs: null };
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            const geo = msg.includes('451');
+            logger.warn(TAG, `probeReachability failed${geo ? ' (HTTP 451 geo-block)' : ''}: ${msg}`);
+            return { outcome: geo ? 'geo_blocked' : 'unreachable', driftMs: null };
+        }
+    }
+}

package/assets/plugin/ccxt/intel-public.d.ts

@@ -0,0 +1,25 @@
+import { type IntelApiDeps } from '../tools/intel-api.js';
+import type { CcxtTicker, CcxtOHLCV } from '../types.js';
+import type { OrderBookDepth } from '../simulator/types.js';
+import type { PublicMarketDataApi } from './public-market-data-api.js';
+type RawCcxt = Record<string, any>;
+export declare class IntelPublicApi implements PublicMarketDataApi {
+    private readonly deps;
+    constructor(deps: IntelApiDeps);
+    /** Latest price for `symbol` as a CcxtTicker (last=bid=ask=intel 1m close;
+     *  zero modeled spread — the paper fill engine models slippage itself).
+     *  Returns null on any intel error, matching BinancePublicApi's contract. */
+    fetchTicker(symbol: string): Promise<CcxtTicker | null>;
+    /** Intel has no raw-ticker/funding/OI HTTP route yet — null (same as a 451). */
+    fetchTickerRaw(): Promise<RawCcxt | null>;
+    fetchFundingRate(): Promise<RawCcxt | null>;
+    fetchOpenInterest(): Promise<RawCcxt | null>;
+    /** No intel depth route yet — null. The paper fill engine falls back to
+     *  random slippage when the book is absent (see helpers.ts fetchOrderBook). */
+    fetchOrderBook(): Promise<OrderBookDepth | null>;
+    /** No intel candle route yet — null (candle-consuming analysis tools degrade
+     *  exactly as they do under a 451; the agent's decisioning reads intel
+     *  signals/scan tools, not raw candles). */
+    fetchOHLCV(): Promise<CcxtOHLCV[] | null>;
+}
+export {};

package/assets/plugin/ccxt/intel-public.js

@@ -0,0 +1,80 @@
+// Intel-backed public market-data source for PAPER mode on hosts that Binance
+// geo-blocks (HTTP 451). Paper execution is fully simulated; it only needs a
+// price, which the intel service serves from its own (permitted-region) feeds
+// via GET /api/price/:symbol (latest 1m close, ≤~60s stale). See
+// docs/AGENT_READINESS_GATE_PLAN.md sibling + the wisekid 451 findings.
+//
+// Selected only when plugin-config `paperMarketDataSource: 'intel'` AND paper
+// mode (index.ts). Live trading NEVER uses this — live needs the real exchange.
+//
+// Increment 1 serves PRICE only (fetchTicker), which is the trading-critical
+// path: create_order / close_position price + the PaperMarketFeed mark loop.
+// Candles / order book / funding / OI have no intel HTTP route yet, so those
+// return null here — the SAME shape a 451 produces today (no regression), and
+// order-book absence is already handled by the fill engine's random-slippage
+// fallback. Candle/book/OI intel routes are a follow-up.
+import { logger } from '../logger.js';
+import { fetchIntelApi } from '../tools/intel-api.js';
+const TAG = 'intel-public';
+/** CCXT symbol (`BTC/USDT`, `BTC/USDT:USDT`) → intel format (`BTCUSDT`). */
+function toIntelSymbol(symbol) {
+    return symbol.replace('/', '').replace(/:.*$/, '');
+}
+export class IntelPublicApi {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+        logger.info(TAG, 'Intel public market-data source active (paper mode, Binance reads routed to intel)');
+    }
+    /** Latest price for `symbol` as a CcxtTicker (last=bid=ask=intel 1m close;
+     *  zero modeled spread — the paper fill engine models slippage itself).
+     *  Returns null on any intel error, matching BinancePublicApi's contract. */
+    async fetchTicker(symbol) {
+        const res = await fetchIntelApi(`/api/price/${toIntelSymbol(symbol)}`, this.deps);
+        if ('error' in res) {
+            logger.warn(TAG, `fetchTicker(${symbol}) via intel failed: ${res.error}`);
+            return null;
+        }
+        const body = res;
+        const price = Number(body.price);
+        if (!Number.isFinite(price) || price <= 0) {
+            logger.warn(TAG, `fetchTicker(${symbol}) via intel returned a bad price: ${body.price}`);
+            return null;
+        }
+        const timestamp = Number.isFinite(body.time) ? body.time : Date.now();
+        return {
+            // Key on the ORIGINAL ccxt symbol so the simulator's per-symbol maps line up.
+            symbol,
+            last: price,
+            bid: price,
+            ask: price,
+            baseVolume: 0,
+            quoteVolume: 0,
+            change: 0,
+            percentage: 0,
+            timestamp,
+            datetime: new Date(timestamp).toISOString(),
+        };
+    }
+    /** Intel has no raw-ticker/funding/OI HTTP route yet — null (same as a 451). */
+    async fetchTickerRaw() {
+        return null;
+    }
+    async fetchFundingRate() {
+        return null;
+    }
+    async fetchOpenInterest() {
+        return null;
+    }
+    /** No intel depth route yet — null. The paper fill engine falls back to
+     *  random slippage when the book is absent (see helpers.ts fetchOrderBook). */
+    async fetchOrderBook() {
+        return null;
+    }
+    /** No intel candle route yet — null (candle-consuming analysis tools degrade
+     *  exactly as they do under a 451; the agent's decisioning reads intel
+     *  signals/scan tools, not raw candles). */
+    async fetchOHLCV() {
+        return null;
+    }
+}

package/assets/plugin/ccxt/public-market-data-api.d.ts

@@ -0,0 +1,26 @@
+import type { CcxtTicker, CcxtOHLCV } from '../types.js';
+import type { OrderBookDepth } from '../simulator/types.js';
+type RawCcxt = Record<string, any>;
+export interface PublicMarketDataApi {
+    fetchTickerRaw(symbol: string): Promise<RawCcxt | null>;
+    fetchTicker(symbol: string): Promise<CcxtTicker | null>;
+    fetchFundingRate(symbol: string): Promise<RawCcxt | null>;
+    fetchOpenInterest(symbol: string): Promise<RawCcxt | null>;
+    fetchOrderBook(symbol: string, limit?: number): Promise<OrderBookDepth | null>;
+    fetchOHLCV(symbol: string, timeframe?: string, limit?: number): Promise<CcxtOHLCV[] | null>;
+}
+/** Which exchange serves the public market-data tools (fetch_ticker,
+ *  fetch_ohlcv, get_orderbook, get_market_structure, …).
+ *
+ *  The configured VENUE decides, in BOTH books — a hyperliquid venue must
+ *  never read Binance prices (live included: the agent would be running
+ *  technical analysis on the wrong exchange's data while trading real money
+ *  on HL). The intel price relay is a Binance-venue, paper-only escape hatch
+ *  for 451-geo-blocked hosts. */
+export declare function resolveMarketDataSource(opts: {
+    venue: 'binance' | 'hyperliquid';
+    isLive: boolean;
+    paperDataSource: 'binance' | 'intel';
+    hasConnectionToken: boolean;
+}): 'hyperliquid' | 'intel' | 'binance';
+export {};

package/assets/plugin/ccxt/public-market-data-api.js

@@ -0,0 +1,23 @@
+// The public market-data surface paper mode reads (prices, candles, book,
+// funding, OI). Both BinancePublicApi (direct Binance) and IntelPublicApi
+// (via the intel service, for Binance-451-geo-blocked hosts) implement it, so
+// the paper wiring can select a source without any consumer knowing which.
+//
+// Deliberately EXCLUDES probeReachability: that is Binance-specific and only
+// the readiness reporter uses it — it must always probe the REAL Binance host
+// to detect the 451, so it keeps a concrete BinancePublicApi, never this.
+/** Which exchange serves the public market-data tools (fetch_ticker,
+ *  fetch_ohlcv, get_orderbook, get_market_structure, …).
+ *
+ *  The configured VENUE decides, in BOTH books — a hyperliquid venue must
+ *  never read Binance prices (live included: the agent would be running
+ *  technical analysis on the wrong exchange's data while trading real money
+ *  on HL). The intel price relay is a Binance-venue, paper-only escape hatch
+ *  for 451-geo-blocked hosts. */
+export function resolveMarketDataSource(opts) {
+    if (opts.venue === 'hyperliquid')
+        return 'hyperliquid';
+    if (!opts.isLive && opts.paperDataSource === 'intel' && opts.hasConnectionToken)
+        return 'intel';
+    return 'binance';
+}

package/assets/plugin/config/agent-config-client.d.ts

@@ -0,0 +1,77 @@
+/** Central operational-gate values. Each gate is validated against its own enum
+ *  PLUGIN-SIDE (§5b: central can never express a value the plugin doesn't
+ *  already consider safe); an invalid field is dropped — field-level fallback,
+ *  never whole-payload rejection. Gates are added one at a time
+ *  (TOOL_DISTRIBUTION_ARCHITECTURE.md §11 step 3): `exitGate` (slice 2) →
+ *  `positionReviewMode` (slice 3, the Position Decision Journal
+ *  heartbeat-mandate + superset gate, file key `positionReview.mode`). Both
+ *  ride the same four-stage `off → shadow → observe → enforce` ladder. */
+export interface AgentGates {
+    exitGate?: 'off' | 'shadow' | 'observe' | 'enforce';
+    positionReviewMode?: 'off' | 'shadow' | 'observe' | 'enforce';
+}
+/** Server-resolved entitlement verdict (webapp lib/entitlements.ts, computed
+ *  from the users row and delivered on the config channel). The plugin NEVER
+ *  re-derives billing state — it consumes `paidAccess` as-is. Absent field =
+ *  unknown = the entitlement gate fails OPEN (older webapp, outage, garbage):
+ *  billing enforcement must never depend on this read succeeding; the
+ *  server-side 403 walls (webapp Pro routes + intel) are the hard layer. */
+export interface AgentEntitlement {
+    state: 'active' | 'trialing' | 'grace' | 'expired' | 'none';
+    paidAccess: boolean;
+    tier?: string;
+    expiresAt?: string;
+    graceUntil?: string;
+}
+/** The slice of /api/internal/config the plugin consumes today. `limits`
+ *  arrives in the payload but is deliberately not modeled yet. */
+export interface AgentConfig {
+    version: number;
+    tools: {
+        disabled: string[];
+    };
+    gates: AgentGates;
+    /** Absent when the server omitted it or the field failed validation. */
+    entitlement?: AgentEntitlement;
+}
+/** Hardcoded safe default — identical to pre-central behavior (nothing
+ *  disabled, no central gate values → local file / defaults rule). */
+export declare function defaultAgentConfig(): AgentConfig;
+/**
+ * Validate an untrusted payload (network response OR cache file) into an
+ * AgentConfig. Returns null when the payload as a whole is malformed —
+ * partial application is never allowed (§5b: central cannot express a value
+ * the plugin doesn't already consider safe).
+ */
+export declare function validateAgentConfig(raw: unknown): AgentConfig | null;
+/** Per-field entitlement validation: a structurally-valid `{state, paidAccess}`
+ *  pair (state in the enum, paidAccess a real boolean) is kept; ANYTHING else
+ *  → undefined, and an absent entitlement makes the gate fail open. Garbage
+ *  can pause new entries only by forging a syntactically-perfect verdict —
+ *  and even then it can never touch closes/stops/emergency (those aren't in
+ *  the gated set at all — see entitlement-gate.ts). */
+export declare function validateEntitlement(raw: unknown): AgentEntitlement | undefined;
+/** Version-monotonic acceptance (basic rollback/replay protection): a fetched
+ *  config older than what we already applied is rejected. Equal versions are
+ *  acceptable (idempotent re-apply is a no-op for the gate). */
+export declare function isAcceptableVersion(fetched: AgentConfig, current: AgentConfig | null): boolean;
+export interface FetchAgentConfigOptions {
+    apiBaseUrl: string;
+    token: string;
+    /** Injectable for unit tests + observability shims. */
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * Fetch the central config. Returns a VALIDATED AgentConfig, or null on any
+ * failure (network, non-200, non-JSON, invalid shape). Never throws.
+ */
+export declare function fetchAgentConfig(opts: FetchAgentConfigOptions): Promise<AgentConfig | null>;
+export declare function defaultCachePath(): string;
+/** Read + validate the cached config. Missing/corrupt/invalid → null (the
+ *  caller falls through to safe defaults). Never throws. */
+export declare function readCachedConfig(path?: string): AgentConfig | null;
+/** Atomically persist the last-known-good config (tmp + rename, 0o600 — the
+ *  plugin-config-io convention). Failures are logged, never thrown: cache
+ *  persistence is an optimization, not a correctness requirement. */
+export declare function writeCachedConfig(config: AgentConfig, path?: string): void;

package/assets/plugin/config/agent-config-client.js

@@ -0,0 +1,188 @@
+// Central per-user agent config — fetch + validate + last-known-good cache.
+//
+// Slice 1 of docs/TOOL_DISTRIBUTION_ARCHITECTURE.md §5: the plugin PULLS
+// `GET /api/internal/config` (webapp, rc_ token → tenant) and applies the
+// tool-enablement OFF-list through the ToolGate. The critical contract (§5b):
+// only a successful, authenticated, VALIDATED, version-acceptable response
+// ever changes behavior. A network error, 5xx, 401, garbage payload, or
+// corrupt cache file can NEVER change what the agent does — the caller keeps
+// the last-known-good config, or the hardcoded safe default (nothing
+// disabled).
+//
+// The cache file lives next to plugin-config.json (`~/.reefclaw/
+// agent-config-cache.json`) and follows the same atomic write convention
+// (tmp + rename, mode 0o600 — see plugin-config-io.ts). It is validated on
+// read with the same validator as the network path: a poisoned cache is as
+// untrusted as a poisoned response.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { logger, formatError } from '../logger.js';
+const TAG = 'agent-config';
+/** Shared four-stage ladder for the gates migrated so far. Kept as one set
+ *  because exitGate + positionReviewMode use identical values; a future gate
+ *  with a different enum gets its own constant. */
+const MODE_LADDER_VALUES = new Set(['off', 'shadow', 'observe', 'enforce']);
+const ENTITLEMENT_STATES = new Set([
+    'active',
+    'trialing',
+    'grace',
+    'expired',
+    'none',
+]);
+/** Hardcoded safe default — identical to pre-central behavior (nothing
+ *  disabled, no central gate values → local file / defaults rule). */
+export function defaultAgentConfig() {
+    return { version: 0, tools: { disabled: [] }, gates: {} };
+}
+/** Tool names must look like tool names. Anything else is dropped — central
+ *  can never smuggle a weird value into the gate's set. */
+const TOOL_NAME_RE = /^[a-z0-9_]{1,64}$/;
+/**
+ * Validate an untrusted payload (network response OR cache file) into an
+ * AgentConfig. Returns null when the payload as a whole is malformed —
+ * partial application is never allowed (§5b: central cannot express a value
+ * the plugin doesn't already consider safe).
+ */
+export function validateAgentConfig(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    const version = obj.version;
+    if (typeof version !== 'number' || !Number.isFinite(version) || version < 0)
+        return null;
+    const tools = obj.tools;
+    if (!tools || typeof tools !== 'object' || Array.isArray(tools))
+        return null;
+    const disabledRaw = tools.disabled;
+    if (!Array.isArray(disabledRaw))
+        return null;
+    const disabled = disabledRaw.filter((v) => typeof v === 'string' && TOOL_NAME_RE.test(v));
+    const config = {
+        version,
+        tools: { disabled },
+        gates: validateGates(obj.gates),
+    };
+    const entitlement = validateEntitlement(obj.entitlement);
+    if (entitlement)
+        config.entitlement = entitlement;
+    return config;
+}
+/** Per-field entitlement validation: a structurally-valid `{state, paidAccess}`
+ *  pair (state in the enum, paidAccess a real boolean) is kept; ANYTHING else
+ *  → undefined, and an absent entitlement makes the gate fail open. Garbage
+ *  can pause new entries only by forging a syntactically-perfect verdict —
+ *  and even then it can never touch closes/stops/emergency (those aren't in
+ *  the gated set at all — see entitlement-gate.ts). */
+export function validateEntitlement(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const obj = raw;
+    const state = obj.state;
+    const paidAccess = obj.paidAccess;
+    if (typeof state !== 'string' || !ENTITLEMENT_STATES.has(state))
+        return undefined;
+    if (typeof paidAccess !== 'boolean')
+        return undefined;
+    const entitlement = {
+        state: state,
+        paidAccess,
+    };
+    if (typeof obj.tier === 'string')
+        entitlement.tier = obj.tier;
+    if (typeof obj.expiresAt === 'string')
+        entitlement.expiresAt = obj.expiresAt;
+    if (typeof obj.graceUntil === 'string')
+        entitlement.graceUntil = obj.graceUntil;
+    return entitlement;
+}
+/** Per-field gate validation (§5b): a structurally-absent/garbage `gates`
+ *  becomes `{}` (no central values → local config rules); each known gate is
+ *  kept only when its value is in that gate's enum. Unknown keys are dropped. */
+function validateGates(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const obj = raw;
+    const gates = {};
+    const exitGate = obj.exitGate;
+    if (typeof exitGate === 'string' && MODE_LADDER_VALUES.has(exitGate)) {
+        gates.exitGate = exitGate;
+    }
+    const positionReviewMode = obj.positionReviewMode;
+    if (typeof positionReviewMode === 'string' && MODE_LADDER_VALUES.has(positionReviewMode)) {
+        gates.positionReviewMode = positionReviewMode;
+    }
+    return gates;
+}
+/** Version-monotonic acceptance (basic rollback/replay protection): a fetched
+ *  config older than what we already applied is rejected. Equal versions are
+ *  acceptable (idempotent re-apply is a no-op for the gate). */
+export function isAcceptableVersion(fetched, current) {
+    if (!current)
+        return true;
+    return fetched.version >= current.version;
+}
+/**
+ * Fetch the central config. Returns a VALIDATED AgentConfig, or null on any
+ * failure (network, non-200, non-JSON, invalid shape). Never throws.
+ */
+export async function fetchAgentConfig(opts) {
+    const { apiBaseUrl, token, fetchImpl = fetch, timeoutMs = 10_000 } = opts;
+    const url = `${apiBaseUrl.replace(/\/+$/, '')}/api/internal/config`;
+    try {
+        const res = await fetchImpl(url, {
+            headers: { authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok) {
+            logger.debug(TAG, `config fetch non-200: ${res.status}`);
+            return null;
+        }
+        const body = (await res.json());
+        const validated = validateAgentConfig(body);
+        if (!validated)
+            logger.warn(TAG, 'config fetch returned an invalid payload — ignored');
+        return validated;
+    }
+    catch (err) {
+        logger.debug(TAG, `config fetch failed: ${formatError(err)}`);
+        return null;
+    }
+}
+// ---- last-known-good cache file ---------------------------------------------
+export function defaultCachePath() {
+    return join(homedir(), '.reefclaw', 'agent-config-cache.json');
+}
+/** Read + validate the cached config. Missing/corrupt/invalid → null (the
+ *  caller falls through to safe defaults). Never throws. */
+export function readCachedConfig(path = defaultCachePath()) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const raw = readFileSync(path, 'utf-8');
+        return validateAgentConfig(JSON.parse(raw));
+    }
+    catch (err) {
+        logger.warn(TAG, `config cache unreadable (${formatError(err)}) — using safe defaults`);
+        return null;
+    }
+}
+/** Atomically persist the last-known-good config (tmp + rename, 0o600 — the
+ *  plugin-config-io convention). Failures are logged, never thrown: cache
+ *  persistence is an optimization, not a correctness requirement. */
+export function writeCachedConfig(config, path = defaultCachePath()) {
+    try {
+        const dir = dirname(path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const tmpPath = `${path}.tmp`;
+        writeFileSync(tmpPath, JSON.stringify(config, null, 2) + '\n', {
+            encoding: 'utf-8',
+            mode: 0o600,
+        });
+        renameSync(tmpPath, path);
+    }
+    catch (err) {
+        logger.warn(TAG, `config cache write failed: ${formatError(err)}`);
+    }
+}

package/assets/plugin/config/agent-config-poller.d.ts

@@ -0,0 +1,32 @@
+import { type AgentConfig, type AgentEntitlement, type AgentGates } from './agent-config-client.js';
+import type { ToolGate } from './tool-gate.js';
+export declare function resolvePollIntervalMs(): number;
+export interface AgentConfigPollerOptions {
+    gate: ToolGate;
+    /** Central operational-gates consumer (slice 2 — exitGate). Optional so the
+     *  tool-allowlist path stands alone; wired from index.ts with the module
+     *  singleton `gateStore`. */
+    gateStore?: {
+        apply(gates: AgentGates): void;
+    };
+    /** Entitlement consumer (account-level enforcement). Optional, wired from
+     *  index.ts with the module singleton `entitlementGate`. Receives the
+     *  config's entitlement slice — including `undefined` when the server
+     *  omitted it, which clears any held verdict (fail-open). */
+    entitlementGate?: {
+        apply(entitlement: AgentEntitlement | undefined): void;
+    };
+    apiBaseUrl: string;
+    token: string;
+    fetchImpl?: typeof fetch;
+    intervalMs?: number;
+    cachePath?: string;
+}
+export interface AgentConfigPollerHandle {
+    stop(): void;
+    /** Exposed for tests/diagnostics — the currently applied config. */
+    getCurrent(): AgentConfig;
+}
+/** Test-only — allows the singleton guard to be reset between unit tests. */
+export declare function __resetPollerSingleton(): void;
+export declare function startAgentConfigPoller(opts: AgentConfigPollerOptions): AgentConfigPollerHandle;