@reefclaw/connect 0.1.12 → 0.1.14

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

@@ -0,0 +1,101 @@
+// Agent-config poller — boots the ToolGate from central config and keeps it
+// fresh (docs/TOOL_DISTRIBUTION_ARCHITECTURE.md §5b).
+//
+// Boot:    fetch → valid + version-acceptable → apply + write cache
+//          fetch fails → last-known-good cache file → apply
+//          nothing     → hardcoded safe default (nothing disabled)
+// Runtime: re-poll every RC_AGENT_CONFIG_POLL_MS (default 60s). Every failed
+//          poll is a keep-last-known-good no-op. Version-lower responses are
+//          rejected (rollback guard). The interval is unref()'d so it never
+//          holds the process open at shutdown.
+//
+// No token → the poller does not start at all: the gate stays empty (all
+// tools on), byte-identical to pre-feature behavior. A module-level singleton
+// guard mirrors `pluginInitialised` in index.ts — OpenClaw calls register()
+// multiple times per process and we must never spawn a second timer.
+import { defaultAgentConfig, fetchAgentConfig, isAcceptableVersion, readCachedConfig, writeCachedConfig, } from './agent-config-client.js';
+import { logger } from '../logger.js';
+const TAG = 'agent-config';
+const DEFAULT_POLL_MS = 60_000;
+const MIN_POLL_MS = 5_000;
+export function resolvePollIntervalMs() {
+    const raw = Number(process.env.RC_AGENT_CONFIG_POLL_MS);
+    if (!Number.isFinite(raw) || raw <= 0)
+        return DEFAULT_POLL_MS;
+    return Math.max(MIN_POLL_MS, raw);
+}
+let pollerStarted = false;
+/** Test-only — allows the singleton guard to be reset between unit tests. */
+export function __resetPollerSingleton() {
+    pollerStarted = false;
+}
+export function startAgentConfigPoller(opts) {
+    const noop = {
+        stop: () => { },
+        getCurrent: () => defaultAgentConfig(),
+    };
+    if (pollerStarted) {
+        logger.warn(TAG, 'poller already started — ignoring duplicate start');
+        return noop;
+    }
+    if (!opts.token || !opts.token.trim()) {
+        logger.info(TAG, 'no connection token — central tool config disabled, all tools enabled (safe default)');
+        return noop;
+    }
+    pollerStarted = true;
+    const intervalMs = opts.intervalMs ?? resolvePollIntervalMs();
+    let current = defaultAgentConfig();
+    let loggedFetchFailure = false;
+    const applyIfAcceptable = (fetched, source) => {
+        if (!isAcceptableVersion(fetched, current)) {
+            logger.warn(TAG, `rejected ${source} config v${fetched.version} < applied v${current.version} (rollback guard)`);
+            return false;
+        }
+        current = fetched;
+        opts.gate.apply(fetched);
+        opts.gateStore?.apply(fetched.gates);
+        opts.entitlementGate?.apply(fetched.entitlement);
+        return true;
+    };
+    const poll = async (isBoot) => {
+        const fetched = await fetchAgentConfig({
+            apiBaseUrl: opts.apiBaseUrl,
+            token: opts.token,
+            fetchImpl: opts.fetchImpl,
+        });
+        if (fetched) {
+            loggedFetchFailure = false;
+            if (applyIfAcceptable(fetched, 'network')) {
+                writeCachedConfig(fetched, opts.cachePath);
+            }
+            return;
+        }
+        if (isBoot) {
+            // Network unavailable at boot — fall back to the last-known-good cache.
+            const cached = readCachedConfig(opts.cachePath);
+            if (cached) {
+                logger.info(TAG, `boot fetch failed — applying last-known-good cache v${cached.version}`);
+                applyIfAcceptable(cached, 'cache');
+            }
+            else {
+                logger.info(TAG, 'boot fetch failed, no cache — safe defaults (all tools enabled)');
+            }
+            return;
+        }
+        // Runtime failure: keep last-known-good silently (log once per outage).
+        if (!loggedFetchFailure) {
+            loggedFetchFailure = true;
+            logger.warn(TAG, `config poll failed — keeping last-known-good v${current.version}`);
+        }
+    };
+    void poll(true);
+    const timer = setInterval(() => {
+        void poll(false);
+    }, intervalMs);
+    timer.unref();
+    logger.info(TAG, `poller started (interval ${Math.round(intervalMs / 1000)}s)`);
+    return {
+        stop: () => clearInterval(timer),
+        getCurrent: () => current,
+    };
+}

package/assets/plugin/config/brackets-config.d.ts

@@ -0,0 +1,22 @@
+import { type PluginConfigFile } from './plugin-config-io.js';
+export type BracketMode = 'off' | 'observe' | 'enforce';
+/** Read bracket mode from a config object. Invalid values fall back to 'off'. */
+export declare function getBracketMode(config?: PluginConfigFile, remoteOverride?: BracketMode): BracketMode;
+/** Convenience: load from disk and return the effective mode. */
+export declare function loadBracketMode(): BracketMode;
+/** Is the feature enabled at all (observe or enforce)? */
+export declare function bracketsEnabled(mode: BracketMode): boolean;
+/** Should the stop-watcher still run alongside brackets? Only 'enforce' turns it off for live. */
+export declare function stopWatcherActiveInLive(mode: BracketMode): boolean;
+/** Per-side requirement flags. Default both true — operator can untick
+ *  individually from the Trading Parameters panel to accept the documented
+ *  risk. Read alongside the bracket mode so a single config read covers
+ *  everything the pre-trade gate needs. */
+export interface BracketRequirements {
+    requireStopLoss: boolean;
+    requireTakeProfit: boolean;
+}
+export declare function getBracketRequirements(config?: PluginConfigFile): BracketRequirements;
+/** Convenience loader. Returns defaults on a missing/corrupt file — same
+ *  policy as loadBracketMode: don't gate trading on a corrupt flag read. */
+export declare function loadBracketRequirements(): BracketRequirements;

package/assets/plugin/config/brackets-config.js

@@ -0,0 +1,58 @@
+// Feature flag reader for the bracket-orders system.
+//
+// Ordering of sources (first hit wins):
+//   1. Remote override from intelligence (set via admin dashboard OTA) — stored
+//      in memory on the plugin after push; not persisted to plugin-config.json.
+//      Wired in Phase 2; for Phase 1 this is always undefined.
+//   2. Local plugin-config.json `brackets.mode` field.
+//   3. Default: 'off' (legacy stop-watcher remains authoritative).
+import { readPluginConfig } from './plugin-config-io.js';
+const VALID = new Set(['off', 'observe', 'enforce']);
+/** Read bracket mode from a config object. Invalid values fall back to 'off'. */
+export function getBracketMode(config, remoteOverride) {
+    if (remoteOverride && VALID.has(remoteOverride))
+        return remoteOverride;
+    const raw = config?.brackets?.mode;
+    if (typeof raw === 'string' && VALID.has(raw)) {
+        return raw;
+    }
+    return 'off';
+}
+/** Convenience: load from disk and return the effective mode. */
+export function loadBracketMode() {
+    try {
+        return getBracketMode(readPluginConfig());
+    }
+    catch {
+        // If plugin-config.json is malformed, we deliberately default to 'off'
+        // rather than throw — other subsystems will alert; trading should not
+        // be gated on bracket-mode reading a corrupt file.
+        return 'off';
+    }
+}
+/** Is the feature enabled at all (observe or enforce)? */
+export function bracketsEnabled(mode) {
+    return mode !== 'off';
+}
+/** Should the stop-watcher still run alongside brackets? Only 'enforce' turns it off for live. */
+export function stopWatcherActiveInLive(mode) {
+    return mode !== 'enforce';
+}
+export function getBracketRequirements(config) {
+    const b = config?.brackets;
+    return {
+        // Explicit `false` turns off; anything else (undefined, true, junk) stays on.
+        requireStopLoss: b?.requireStopLoss !== false,
+        requireTakeProfit: b?.requireTakeProfit !== false,
+    };
+}
+/** Convenience loader. Returns defaults on a missing/corrupt file — same
+ *  policy as loadBracketMode: don't gate trading on a corrupt flag read. */
+export function loadBracketRequirements() {
+    try {
+        return getBracketRequirements(readPluginConfig());
+    }
+    catch {
+        return { requireStopLoss: true, requireTakeProfit: true };
+    }
+}

package/assets/plugin/config/entitlement-gate.d.ts

@@ -0,0 +1,51 @@
+import type { AgentEntitlement } from './agent-config-client.js';
+/** The ONLY tools an expired entitlement may pause. Deliberately a denylist
+ *  (not "everything except safety"): a tool added tomorrow is un-gated by
+ *  default, which is the conservative failure mode in a trading product.
+ *  Intel/data tools are NOT here — the intelligence service and webapp 403
+ *  those server-side with the same actionable message. */
+export declare const ENTITLEMENT_GATED_TOOLS: ReadonlySet<string>;
+export type EntitlementGateMode = 'enforce' | 'shadow' | 'off';
+export declare function resolveEntitlementGateMode(): EntitlementGateMode;
+/** Structured, agent-visible result for a blocked call. Worded so the agent
+ *  stops cleanly (no retry loop), keeps managing the existing book, and tells
+ *  the operator exactly how to restore service. */
+export declare function entitlementBlockedResult(name: string): {
+    ok: false;
+    error: 'entitlement_expired';
+    tool: string;
+    message: string;
+};
+/** Minimal structural view of a registered plugin tool — same shape as
+ *  tool-gate.ts GateablePluginTool (kept local to avoid a cross-module type
+ *  dependency for one interface). */
+export interface EntitlementGateableTool {
+    name: string;
+    execute: (...args: any[]) => any;
+}
+export declare class EntitlementGate {
+    private readonly mode;
+    private entitlement;
+    /** Avoids log spam: one line per state transition, not per blocked call. */
+    private lastLoggedKey;
+    constructor(mode?: EntitlementGateMode);
+    getMode(): EntitlementGateMode;
+    getEntitlement(): AgentEntitlement | undefined;
+    /** Apply the entitlement slice of a validated config (poller path).
+     *  `undefined` (server omitted it / validation dropped it) CLEARS the held
+     *  verdict — the gate then fails open rather than enforcing a stale one
+     *  the server no longer asserts. */
+    apply(entitlement: AgentEntitlement | undefined): void;
+    /** Should this call be blocked? Non-gated names short-circuit FIRST (the
+     *  safety set can never be touched, in any mode, with any payload); then
+     *  only an explicit server verdict of paidAccess=false blocks. */
+    isBlocked(name: string): boolean;
+    /** Wrap a tool's execute with the gate check — same hot-apply pattern as
+     *  ToolGate.wrapTool (state is consulted per call, not at registration). */
+    wrapTool<T extends EntitlementGateableTool>(tool: T, jsonResult: (data: unknown) => unknown): T;
+    /** Test-only. */
+    __reset(): void;
+}
+/** Module singleton — one gate per plugin process, shared by the poller
+ *  (writer) and the tool-wrap in index.ts (consumer), mirroring gateStore. */
+export declare const entitlementGate: EntitlementGate;

package/assets/plugin/config/entitlement-gate.js

@@ -0,0 +1,137 @@
+// EntitlementGate — the plugin-side enforcement point for account-level
+// (billing) restrictions: when the server-resolved entitlement says the user
+// has no paid access (trial expired past its end, subscription lapsed past
+// the 7-day grace), NEW ENTRIES pause. Everything else keeps working.
+//
+// ★ SAFETY ANALYSIS (why this can never add risk to an existing book):
+// the gate blocks ONLY the names in ENTITLEMENT_GATED_TOOLS — today exactly
+// `create_order`, the one tool that ADDS risk and the one thing our servers
+// cannot 403 (it goes plugin → Binance directly). Every risk-REDUCING and
+// safety path (close_position, modify_stop, attach_brackets,
+// audit_bracket_protection, record_position_reviews, the operator-control
+// tools, kill/flatten/pause via the skill) is untouched by construction: it
+// is not in the gated set, and a pin test asserts the set can never grow into
+// the safety floor. This mirrors what an auto-pause on loss limits already
+// does (no new entries, existing positions fully manageable) — an operation
+// the product already considers safe.
+//
+// ★ THREAT MODEL HONESTY: the plugin runs on the trader's own hardware, so
+// this gate is the COURTESY layer — it makes the agent stop cleanly with an
+// actionable message instead of burning failed calls. The HARD enforcement is
+// server-side: webapp Pro routes and the intelligence API both 403 on
+// paidAccess=false, which removes the data the agent trades on.
+//
+// Fail direction: no entitlement data (older webapp, outage, garbage payload,
+// no token) → ALLOW. Billing enforcement must never brick a paying customer
+// because our config channel hiccuped; last-known-good semantics come from
+// the agent-config cache like every other centrally-delivered value.
+//
+// Kill-switch: RC_ENTITLEMENT_GATE=off (never blocks) | shadow (log-only)
+// | default enforce — same convention as RC_TOOL_GATE / RC_CENTRAL_GATES.
+import { logger } from '../logger.js';
+const TAG = 'entitlement-gate';
+/** The ONLY tools an expired entitlement may pause. Deliberately a denylist
+ *  (not "everything except safety"): a tool added tomorrow is un-gated by
+ *  default, which is the conservative failure mode in a trading product.
+ *  Intel/data tools are NOT here — the intelligence service and webapp 403
+ *  those server-side with the same actionable message. */
+export const ENTITLEMENT_GATED_TOOLS = new Set(['create_order']);
+export function resolveEntitlementGateMode() {
+    const raw = (process.env.RC_ENTITLEMENT_GATE ?? '').toLowerCase();
+    if (raw === 'off')
+        return 'off';
+    if (raw === 'shadow')
+        return 'shadow';
+    return 'enforce';
+}
+/** Structured, agent-visible result for a blocked call. Worded so the agent
+ *  stops cleanly (no retry loop), keeps managing the existing book, and tells
+ *  the operator exactly how to restore service. */
+export function entitlementBlockedResult(name) {
+    return {
+        ok: false,
+        error: 'entitlement_expired',
+        tool: name,
+        message: `New entries are paused: the ReefClaw subscription for this connection has expired ` +
+            `(trial ended or payment lapsed). Do not retry this call. Existing positions remain fully ` +
+            `manageable — close_position, modify_stop, attach_brackets, and all emergency/operator ` +
+            `controls work normally, and protective brackets stay enforced by the exchange. ` +
+            `Tell your operator to renew at https://reefclaw.com (Settings → Billing) to resume trading.`,
+    };
+}
+export class EntitlementGate {
+    mode;
+    entitlement;
+    /** Avoids log spam: one line per state transition, not per blocked call. */
+    lastLoggedKey = '';
+    constructor(mode = resolveEntitlementGateMode()) {
+        this.mode = mode;
+        if (mode !== 'enforce')
+            logger.info(TAG, `mode=${mode}`);
+    }
+    getMode() {
+        return this.mode;
+    }
+    getEntitlement() {
+        return this.entitlement;
+    }
+    /** Apply the entitlement slice of a validated config (poller path).
+     *  `undefined` (server omitted it / validation dropped it) CLEARS the held
+     *  verdict — the gate then fails open rather than enforcing a stale one
+     *  the server no longer asserts. */
+    apply(entitlement) {
+        const key = entitlement ? `${entitlement.state}:${entitlement.paidAccess}` : '(none)';
+        if (key !== this.lastLoggedKey) {
+            this.lastLoggedKey = key;
+            logger.info(TAG, entitlement
+                ? `entitlement: state=${entitlement.state} paidAccess=${entitlement.paidAccess}` +
+                    (entitlement.graceUntil ? ` graceUntil=${entitlement.graceUntil}` : '')
+                : 'entitlement: no server verdict — gate inactive (fail-open)');
+        }
+        this.entitlement = entitlement;
+    }
+    /** Should this call be blocked? Non-gated names short-circuit FIRST (the
+     *  safety set can never be touched, in any mode, with any payload); then
+     *  only an explicit server verdict of paidAccess=false blocks. */
+    isBlocked(name) {
+        if (this.mode === 'off')
+            return false;
+        if (!ENTITLEMENT_GATED_TOOLS.has(name))
+            return false;
+        if (!this.entitlement)
+            return false; // unknown → allow
+        if (this.entitlement.paidAccess !== false)
+            return false;
+        if (this.mode === 'shadow') {
+            logger.info(TAG, `SHADOW: would block ${name} (state=${this.entitlement.state})`);
+            return false;
+        }
+        return true;
+    }
+    /** Wrap a tool's execute with the gate check — same hot-apply pattern as
+     *  ToolGate.wrapTool (state is consulted per call, not at registration). */
+    wrapTool(tool, jsonResult) {
+        if (!ENTITLEMENT_GATED_TOOLS.has(tool.name))
+            return tool;
+        const originalExecute = tool.execute.bind(tool);
+        return {
+            ...tool,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            execute: (...args) => {
+                if (this.isBlocked(tool.name)) {
+                    logger.info(TAG, `blocked ${tool.name} (entitlement state=${this.entitlement?.state ?? 'unknown'})`);
+                    return Promise.resolve(jsonResult(entitlementBlockedResult(tool.name)));
+                }
+                return originalExecute(...args);
+            },
+        };
+    }
+    /** Test-only. */
+    __reset() {
+        this.entitlement = undefined;
+        this.lastLoggedKey = '';
+    }
+}
+/** Module singleton — one gate per plugin process, shared by the poller
+ *  (writer) and the tool-wrap in index.ts (consumer), mirroring gateStore. */
+export const entitlementGate = new EntitlementGate();

package/assets/plugin/config/gate-store.d.ts

@@ -0,0 +1,18 @@
+import type { AgentGates } from './agent-config-client.js';
+declare class GateStore {
+    private gates;
+    /** Apply a validated gates object (poller path). Logs only on change. */
+    apply(gates: AgentGates): void;
+    /** The central exitGate mode, or null when central has no value (or the
+     *  kill-switch is on) — null tells the reader to fall back to the file. */
+    getExitGate(): AgentGates['exitGate'] | null;
+    /** The central positionReview.mode, or null when central has no value (or the
+     *  kill-switch is on) — null tells the reader to fall back to the file. */
+    getPositionReviewMode(): AgentGates['positionReviewMode'] | null;
+    /** Test-only. */
+    __reset(): void;
+}
+/** Module singleton — one store per plugin process, shared by the poller
+ *  (writer) and the config readers (consumers). */
+export declare const gateStore: GateStore;
+export {};

package/assets/plugin/config/gate-store.js

@@ -0,0 +1,61 @@
+// GateStore — the plugin-side holder for centrally-delivered operational-gate
+// values (TOOL_DISTRIBUTION_ARCHITECTURE.md §11 step 3; slice 2 = exitGate,
+// slice 3 = positionReviewMode).
+//
+// The agent-config poller applies each validated config's `gates` here; the
+// per-feature config readers (position-review-config.ts loadExitGateMode +
+// loadPositionReviewMode) consult the store FIRST and fall back to the local
+// plugin-config.json when no central value is present:
+//
+//     central (this store) → ~/.reefclaw/plugin-config.json → hardcoded default
+//
+// Values in the store have already passed the plugin-side enum validation in
+// agent-config-client.ts (validateGates) — central can never deliver a value
+// outside a gate's enum (§5b). A config-server outage never lands here either:
+// the poller keeps last-known-good, and with no applied config the store is
+// empty → the local file rules, byte-identical to pre-central behavior.
+//
+// Kill-switch: RC_CENTRAL_GATES=off makes the store report no central values
+// (local file rules again) without a redeploy — same convention as
+// RC_TOOL_GATE for the tool allowlist.
+import { logger } from '../logger.js';
+const TAG = 'gate-store';
+function centralGatesEnabled() {
+    return (process.env.RC_CENTRAL_GATES ?? '').toLowerCase() !== 'off';
+}
+const UNSET = '(unset — local config rules)';
+class GateStore {
+    gates = {};
+    /** Apply a validated gates object (poller path). Logs only on change. */
+    apply(gates) {
+        const next = gates ?? {};
+        const changed = next.exitGate !== this.gates.exitGate ||
+            next.positionReviewMode !== this.gates.positionReviewMode;
+        this.gates = { ...next };
+        if (changed) {
+            logger.info(TAG, `applied central gates: exitGate=${next.exitGate ?? UNSET} ` +
+                `positionReviewMode=${next.positionReviewMode ?? UNSET}`);
+        }
+    }
+    /** The central exitGate mode, or null when central has no value (or the
+     *  kill-switch is on) — null tells the reader to fall back to the file. */
+    getExitGate() {
+        if (!centralGatesEnabled())
+            return null;
+        return this.gates.exitGate ?? null;
+    }
+    /** The central positionReview.mode, or null when central has no value (or the
+     *  kill-switch is on) — null tells the reader to fall back to the file. */
+    getPositionReviewMode() {
+        if (!centralGatesEnabled())
+            return null;
+        return this.gates.positionReviewMode ?? null;
+    }
+    /** Test-only. */
+    __reset() {
+        this.gates = {};
+    }
+}
+/** Module singleton — one store per plugin process, shared by the poller
+ *  (writer) and the config readers (consumers). */
+export const gateStore = new GateStore();