@reefclaw/connect 0.1.11 → 0.1.12

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

@@ -1,101 +0,0 @@
-// 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

@@ -1,22 +0,0 @@
-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

@@ -1,58 +0,0 @@
-// 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

@@ -1,51 +0,0 @@
-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

@@ -1,137 +0,0 @@
-// 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

@@ -1,18 +0,0 @@
-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

@@ -1,61 +0,0 @@
-// 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();