@reefclaw/openclaw-plugin 0.1.0

package/tools/propose-learning.d.ts

@@ -0,0 +1,22 @@
+import type { PositionDecisionsClient, ProposeLearningResponse } from '../ingest/position-decisions-client.js';
+export interface ProposeLearningArgs {
+    applies_at: 'entry' | 'heartbeat' | 'close';
+    title: string;
+    directive: string;
+    source_mined_pattern_id?: string;
+    trigger_condition?: Record<string, unknown>;
+    evidence?: Record<string, unknown>;
+}
+export interface ProposeLearningDeps {
+    decisionsClient?: PositionDecisionsClient;
+    userId?: string;
+}
+export type ProposeLearningResult = (ProposeLearningResponse & {
+    ok: true;
+}) | {
+    error: string;
+    throttled?: boolean;
+    proposals_used?: number;
+    proposals_limit?: number;
+};
+export declare function proposeLearningTool(args: ProposeLearningArgs, deps: ProposeLearningDeps): Promise<ProposeLearningResult>;

package/tools/propose-learning.js

@@ -0,0 +1,65 @@
+// Tool: propose_learning — Phase 4.5 agent-side write capability.
+//
+// The agent calls this once per UTC day during its self-assessment routine,
+// after reading get_my_mined_patterns + get_my_proposed_learnings, to draft a
+// new candidate learning for its operator to review.
+//
+// Critically:
+//   - confidence is determined SERVER-SIDE by the operator's trust mode.
+//     The agent never writes 'confirmed' directly. Under trust=auto, the
+//     server flips confidence='confirmed' + auto_confirmed=true so the
+//     proposal takes effect immediately.
+//   - proposed_by is hardcoded 'agent' in the route — never trusted from
+//     this caller.
+//   - Server-side throttle of 3 proposals per 24h per user means most days
+//     the agent will draft 0-3, not 30.
+//
+// Directive style guide (enforced in SKILL.md, not in code, to preserve
+// agency over wording): n / effect size / p / a recent concrete example /
+// default action / override conditions.
+import { logger, formatError } from '../logger.js';
+const TAG = 'propose-learning';
+const APPLIES_AT_VALUES = new Set(['entry', 'heartbeat', 'close']);
+export async function proposeLearningTool(args, deps) {
+    if (!deps.decisionsClient || !deps.userId) {
+        return { error: 'Position-decisions ingest is not configured; cannot propose learnings.' };
+    }
+    if (!args.applies_at || !APPLIES_AT_VALUES.has(args.applies_at)) {
+        return { error: "applies_at is required and must be one of: 'entry', 'heartbeat', 'close'." };
+    }
+    if (typeof args.title !== 'string' || args.title.trim().length < 4) {
+        return { error: 'title required (min 4 chars).' };
+    }
+    if (typeof args.directive !== 'string' || args.directive.trim().length < 20) {
+        return { error: 'directive required (min 20 chars).' };
+    }
+    let response;
+    try {
+        response = await deps.decisionsClient.proposeLearning(deps.userId, {
+            appliesAt: args.applies_at,
+            title: args.title.trim(),
+            directive: args.directive.trim(),
+            sourceMinedPatternId: args.source_mined_pattern_id,
+            triggerCondition: args.trigger_condition,
+            evidence: args.evidence,
+        });
+    }
+    catch (err) {
+        logger.warn(TAG, `proposeLearning threw: ${formatError(err)}`);
+        return { error: 'Failed to post proposal to webapp.' };
+    }
+    if (!response) {
+        // The client treats 4xx as terminal-dropped and 5xx+network as retry-
+        // exhausted. Either way we get null and surface a generic error. The
+        // throttle status (429) would have been a 4xx terminal drop without a
+        // structured body returned through this path — agent can call
+        // get_my_proposed_learnings to check.
+        return {
+            error: 'Proposal was not accepted (could be throttled, validation error, or network failure). Inspect logs and recent proposals to diagnose.',
+        };
+    }
+    return {
+        ok: true,
+        ...response,
+    };
+}

package/tools/query-review-outcomes.d.ts

@@ -0,0 +1,30 @@
+import type { PositionDecisionsClient, ReviewOutcomesResponse } from '../ingest/position-decisions-client.js';
+export interface QueryReviewOutcomesArgs {
+    verdict?: 'hold' | 'add_on' | 'close_recommended';
+    thesis_status?: 'intact' | 'weakening' | 'invalidated' | 'evolving';
+    regime_current?: string;
+    symbol?: string;
+    side?: 'long' | 'short';
+    setup_type?: string;
+    days_back?: number;
+    min_score_delta?: number;
+    max_score_delta?: number;
+    closed_only?: boolean;
+    sample_limit?: number;
+}
+export interface QueryReviewOutcomesDeps {
+    decisionsClient?: PositionDecisionsClient;
+    userId?: string;
+}
+export type QueryReviewOutcomesResult = (ReviewOutcomesResponse & {
+    ok: true;
+}) | {
+    ok: true;
+    note: string;
+    filters: Record<string, unknown>;
+    stats: ReviewOutcomesResponse['stats'];
+    sample: [];
+} | {
+    error: string;
+};
+export declare function queryReviewOutcomesTool(args: QueryReviewOutcomesArgs, deps: QueryReviewOutcomesDeps): Promise<QueryReviewOutcomesResult>;

package/tools/query-review-outcomes.js

@@ -0,0 +1,64 @@
+// Tool: query_review_outcomes — Phase 2 of the Agent Learning Loop.
+//
+// Aggregate-stats + sample over the position_review_outcomes view. Lets the
+// agent ask "what happened to positions where I filed verdict=hold +
+// thesis_status=weakening over the last 7 days?" and receive a count, win
+// rate, median R, and a small sample of matching reviews.
+//
+// Use case: at session start (and daily), the agent runs this for its
+// most-used (verdict, thesis_status) combinations. Any combination showing
+// median R < 0 across 5+ closed samples is the agent's evidence that the
+// pattern is bleeding edge.
+//
+// See docs/AGENT_LEARNING_LOOP_PLAN.md §3 Phase 2.
+import { logger, formatError } from '../logger.js';
+const TAG = 'query-review-outcomes';
+export async function queryReviewOutcomesTool(args, deps) {
+    if (!deps.decisionsClient || !deps.userId) {
+        return {
+            ok: true,
+            note: 'Position-decisions ingest is not configured; outcomes are unavailable.',
+            filters: { ...args },
+            stats: emptyStats(),
+            sample: [],
+        };
+    }
+    const filters = {
+        verdict: args.verdict,
+        thesisStatus: args.thesis_status,
+        regimeCurrent: args.regime_current,
+        symbol: args.symbol,
+        side: args.side,
+        setupType: args.setup_type,
+        daysBack: args.days_back,
+        minScoreDelta: args.min_score_delta,
+        maxScoreDelta: args.max_score_delta,
+        closedOnly: args.closed_only,
+        sampleLimit: args.sample_limit,
+    };
+    let response;
+    try {
+        response = await deps.decisionsClient.queryReviewOutcomes(deps.userId, filters);
+    }
+    catch (err) {
+        logger.warn(TAG, `queryReviewOutcomes threw: ${formatError(err)}`);
+        return { error: 'Failed to fetch review outcomes from webapp.' };
+    }
+    if (!response) {
+        return { error: 'Webapp /api/internal/positions/reviews/with-outcomes returned no result.' };
+    }
+    return { ok: true, ...response };
+}
+function emptyStats() {
+    return {
+        nTotal: 0,
+        nClosed: 0,
+        winRate: null,
+        medianR: null,
+        meanR: null,
+        medianGiveBack: null,
+        p25R: null,
+        p75R: null,
+        outcomeCounts: {},
+    };
+}

package/tools/query-trades.d.ts

@@ -0,0 +1,21 @@
+import type { IntelApiDeps } from './intel-api.js';
+export interface QueryTradesArgs {
+    symbol?: string;
+    setup_type?: string;
+    strategy?: string;
+    regime?: string;
+    direction?: string;
+    outcome?: string;
+    min_duration_seconds?: number;
+    max_duration_seconds?: number;
+    min_pnl_pct?: number;
+    max_pnl_pct?: number;
+    min_confluence_score?: number;
+    hours?: number;
+    feature_filters?: string;
+    group_by?: string;
+    limit?: number;
+}
+export declare function queryTradesTool(args: QueryTradesArgs, deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/query-trades.js

@@ -0,0 +1,37 @@
+// Tool: query_trades — flexible trade history query with filters + aggregation.
+// Lets the agent ask arbitrary questions about its own performance:
+// "what's my win rate when ADX > 40?", "best setup per regime?", etc.
+import { fetchIntelApi } from './intel-api.js';
+export async function queryTradesTool(args, deps) {
+    // Parse feature_filters from JSON string if provided
+    let featureFilters;
+    if (args.feature_filters) {
+        try {
+            featureFilters = JSON.parse(args.feature_filters);
+        }
+        catch {
+            return { error: 'feature_filters must be valid JSON array, e.g. [{"field":"adx","op":"gt","value":40}]' };
+        }
+    }
+    return fetchIntelApi('/api/trades/query', deps, {
+        method: 'POST',
+        body: {
+            symbol: args.symbol,
+            setup_type: args.setup_type,
+            strategy: args.strategy,
+            regime: args.regime,
+            direction: args.direction,
+            outcome: args.outcome,
+            min_duration_seconds: args.min_duration_seconds,
+            max_duration_seconds: args.max_duration_seconds,
+            min_pnl_pct: args.min_pnl_pct,
+            max_pnl_pct: args.max_pnl_pct,
+            min_confluence_score: args.min_confluence_score,
+            hours: args.hours,
+            feature_filters: featureFilters,
+            group_by: args.group_by,
+            limit: args.limit,
+        },
+        timeoutMs: 15_000,
+    });
+}

package/tools/record-position-reviews.d.ts

@@ -0,0 +1,38 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import { type RecordPositionReviewsArgs } from './assessment-validation.js';
+import type { PositionDecisionsClient } from '../ingest/position-decisions-client.js';
+import type { PositionStateStore } from '../live/position-state-store.js';
+import type { MicrostructureAssembler } from '../live/microstructure-assembler.js';
+export interface RecordPositionReviewsDeps {
+    adapter: IExchangeAdapter;
+    decisionsClient?: PositionDecisionsClient;
+    stateStore?: PositionStateStore;
+    /** User id used for the webapp ingest header. */
+    userId?: string;
+    /** Current gate mode — drives the superset rule. */
+    gateMode?: 'off' | 'shadow' | 'observe' | 'enforce';
+    /** Optional snapshot of currently-open symbols at heartbeat-tick time.
+     *  Plugin embeds this into the heartbeat result; agent passes it through.
+     *  When absent we derive from adapter.getPositions(). */
+    openSymbolsSnapshot?: ReadonlySet<string>;
+    /** Optional pre-fetched microstructure context — when supplied, the tool
+     *  fills review rows from this map without going to the assembler. Used by
+     *  tests that don't want to mock the network. */
+    microstructureBySymbol?: Map<string, {
+        restingBandImbalance05?: number;
+        cascadePulse60s?: 'quiet' | 'elevated' | 'active_cascade';
+        coverageBpc?: number;
+    }>;
+    /** When provided AND `microstructureBySymbol` is NOT supplied, the tool
+     *  fetches microstructure for every reviewed symbol via the assembler
+     *  before processing reviews. Resolves PR1 deferral #3. */
+    microstructureAssembler?: MicrostructureAssembler;
+}
+export interface RecordPositionReviewsResult {
+    ok: boolean;
+    filed: number;
+    error?: string;
+}
+export declare function recordPositionReviewsTool(args: RecordPositionReviewsArgs, deps: RecordPositionReviewsDeps): Promise<RecordPositionReviewsResult | {
+    error: string;
+}>;

package/tools/record-position-reviews.js

@@ -0,0 +1,147 @@
+// Tool: record_position_reviews — plural-form per-heartbeat-per-open-position
+// review filing. Schema-validated like v2.10.0 close validator. POSTs each
+// review to the webapp's /api/internal/position-reviews endpoint and updates
+// the local position-state-store's lastReviewAt for stale-gate evaluation.
+//
+// Mode behavior (positionReview.mode in plugin-config):
+//   - off       : tool callable, validator runs, but no SKILL.md mandate.
+//                  Used while feature is being soaked.
+//   - shadow    : SKILL.md mandates the call; validator only runs per-review.
+//   - observe   : same as shadow + soft-warn create_order on stale review.
+//   - enforce   : same + superset rule + hard-reject create_order on stale.
+//
+// Auto-capture of orderbook context (microstructure.heartbeatPush='on'):
+//   the agent need not pass restingBandImbalance05 / cascadePulseAtReview /
+//   coveragePctAtReview — the tool fills them from the latest intel reading.
+//   When the flag is off, fields stay null.
+//
+// See docs/POSITION_DECISION_JOURNAL_PLAN.md.
+import { logger, formatError } from '../logger.js';
+import { validatePositionReviews, } from './assessment-validation.js';
+import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
+const TAG = 'record-position-reviews';
+export async function recordPositionReviewsTool(args, deps) {
+    // Build the open-symbols snapshot for the superset check.
+    // Normalize every symbol — Binance live form returns settle-suffixed
+    // 'SOL/USDT:USDT' while the state-store + agent-side reviews use the
+    // canonical 'SOL/USDT'. Without this the superset check rejects every
+    // heartbeat and the discipline gate becomes a brick wall.
+    let openSymbols;
+    if (deps.openSymbolsSnapshot) {
+        openSymbols = new Set(Array.from(deps.openSymbolsSnapshot, normalizeBracketSymbol));
+    }
+    else {
+        let positions;
+        try {
+            positions = await deps.adapter.getPositionsOrNull();
+        }
+        catch (err) {
+            logger.warn(TAG, `getPositions threw for superset check: ${formatError(err)}`);
+            positions = null;
+        }
+        if (positions === null) {
+            // Fetch failed / threw — the open-position set is UNKNOWN, not empty.
+            // In enforce mode the superset rule iterates ctx.openSymbols; an empty
+            // set makes `missing` empty so the gate trivially PASSES — i.e. the
+            // agent could file zero reviews during a rate-limit window and the
+            // discipline gate would silently miss it. Reject so the agent retries
+            // next heartbeat (same null != empty contract as audit / reconciler).
+            // At lower gate modes the superset rule never runs (openSymbols unused),
+            // so proceeding with an empty set is harmless.
+            const mode = deps.gateMode ?? 'off';
+            if (mode === 'enforce') {
+                logger.warn(TAG, 'getPositions unavailable (null) in enforce mode — cannot verify review superset; rejecting for retry');
+                return {
+                    error: 'Exchange position state unavailable — cannot verify review coverage. Retry next heartbeat.',
+                };
+            }
+            logger.warn(TAG, 'getPositions unavailable (null); proceeding (superset gate not enforced at this mode)');
+            openSymbols = new Set();
+        }
+        else {
+            openSymbols = new Set(positions.map((p) => normalizeBracketSymbol(p.symbol)));
+        }
+    }
+    // Validator gate.
+    const v = validatePositionReviews(args, {
+        openSymbols,
+        gateMode: deps.gateMode ?? 'off',
+    });
+    if (!v.ok) {
+        logger.warn(TAG, `record_position_reviews rejected: ${v.error}`);
+        return { error: v.error ?? 'Invalid record_position_reviews arguments.' };
+    }
+    // Cast — validator confirmed the shape.
+    const reviews = args.reviews.slice();
+    // Resolve microstructure context. Caller-supplied map wins (tests); else
+    // fetch via the assembler (live path). Returns an empty map when the
+    // heartbeatPush flag is off — review rows then get null orderbook fields.
+    let microstructure = deps.microstructureBySymbol;
+    if (!microstructure && deps.microstructureAssembler) {
+        try {
+            const symbols = reviews
+                .map((r) => r.symbol)
+                .filter((s) => typeof s === 'string' && s.length > 0);
+            microstructure = await deps.microstructureAssembler.forSymbols(symbols);
+        }
+        catch (err) {
+            logger.warn(TAG, `microstructure fetch threw — proceeding with null fields: ${formatError(err)}`);
+            microstructure = new Map();
+        }
+    }
+    // Forward each review to the webapp + update local state-store.
+    // We POST in parallel — they target append-only endpoints and the order is
+    // not load-bearing (each row carries its own reviewAt).
+    let filed = 0;
+    if (deps.decisionsClient && deps.userId) {
+        const promises = [];
+        for (const r of reviews) {
+            const stateEntry = deps.stateStore?.get(r.symbol);
+            const positionId = stateEntry?.webappPositionId;
+            if (!positionId) {
+                logger.warn(TAG, `No webappPositionId for ${r.symbol} — review will not be persisted to webapp until the position upserts.`);
+                continue;
+            }
+            const micro = microstructure?.get(r.symbol);
+            const payload = {
+                positionId,
+                reviewAt: Date.now(),
+                verdict: r.verdict,
+                thesisStatus: r.thesis_status,
+                entryScore: r.entry_score,
+                currentScore: r.current_score,
+                scoreDelta: r.score_delta,
+                confluenceComponents: r.confluence_components ?? {},
+                regimeEntry: r.regime_entry,
+                regimeCurrent: r.regime_current,
+                regimeConfidence: r.regime_confidence,
+                rMultiple: r.r_multiple,
+                distanceToStopBps: r.distance_to_stop_bps,
+                distanceToTargetBps: r.distance_to_target_bps ?? null,
+                timeInPositionMinutes: r.time_in_position_minutes,
+                mfeR: r.mfe_r,
+                giveBackPct: r.give_back_pct,
+                whatChanged: r.what_changed,
+                invalidationTrigger: r.invalidation_trigger,
+                // Auto-filled microstructure when push is on.
+                restingBandImbalance05: micro?.restingBandImbalance05 ?? null,
+                cascadePulseAtReview: micro?.cascadePulse60s ?? null,
+                coveragePctAtReview: micro?.coverageBpc != null ? micro.coverageBpc / 100 : null,
+                imbalanceDeltaSinceEntry: null, // filled in once we add per-position imbalance baselines
+            };
+            // Fire-and-forget — caller doesn't block on the network.
+            deps.decisionsClient.postReview(deps.userId, payload);
+            filed++;
+            // Update state-store for stale-gate + exit-gate.
+            if (deps.stateStore) {
+                deps.stateStore.recordReview(r.symbol, r.verdict, undefined, r.thesis_status);
+            }
+        }
+        await Promise.allSettled(promises);
+    }
+    else {
+        logger.info(TAG, `record_position_reviews validated ${reviews.length} reviews; no decisionsClient configured (off-mode).`);
+        filed = 0;
+    }
+    return { ok: true, filed };
+}

package/tools/save-strategy.d.ts

@@ -0,0 +1,16 @@
+import type { IntelApiDeps } from './intel-api.js';
+export interface SaveStrategyArgs {
+    name: string;
+    description?: string;
+    regimes: string;
+    direction_rule: string;
+    conditions: string;
+    entry_type: string;
+    entry_params?: string;
+    stop_type: string;
+    stop_params?: string;
+    target_r_multiples: string;
+}
+export declare function saveStrategyTool(args: SaveStrategyArgs, deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/save-strategy.js

@@ -0,0 +1,46 @@
+// Tool: save_strategy — create or update a strategy in the Strategy Box.
+// Posts a declarative strategy config to the Intelligence API.
+import { fetchIntelApi } from './intel-api.js';
+export async function saveStrategyTool(args, deps) {
+    let conditions;
+    try {
+        conditions = JSON.parse(args.conditions);
+    }
+    catch {
+        return { error: 'conditions must be valid JSON array of {type, params} objects' };
+    }
+    let entryParams = {};
+    if (args.entry_params) {
+        try {
+            entryParams = JSON.parse(args.entry_params);
+        }
+        catch {
+            return { error: 'entry_params must be valid JSON' };
+        }
+    }
+    let stopParams = {};
+    if (args.stop_params) {
+        try {
+            stopParams = JSON.parse(args.stop_params);
+        }
+        catch {
+            return { error: 'stop_params must be valid JSON' };
+        }
+    }
+    const config = {
+        name: args.name,
+        description: args.description ?? '',
+        version: 1,
+        regimeWhitelist: args.regimes.split(',').map(s => s.trim()),
+        minConfidence: 0.7,
+        directionRule: args.direction_rule,
+        conditions,
+        entryRule: { type: args.entry_type, params: entryParams },
+        stopRule: { type: args.stop_type, params: stopParams },
+        targetRMultiples: args.target_r_multiples.split(',').map(s => parseFloat(s.trim())),
+    };
+    return fetchIntelApi('/api/strategies', deps, {
+        method: 'POST',
+        body: config,
+    });
+}

package/tools/scan-pairs.d.ts

@@ -0,0 +1,18 @@
+import type { IntelApiDeps } from './intel-api.js';
+import type { PositionDecisionsClient } from '../ingest/position-decisions-client.js';
+export interface ScanPairsArgs {
+    /** Minimum confluence score (number of conditions met) to include in rankings. */
+    min_score?: number;
+    /** Optional whitelist of symbols to scan. When omitted, scans all configured pairs. */
+    symbols?: string[];
+}
+export interface ScanPairsDecisionsDeps {
+    decisionsClient?: PositionDecisionsClient;
+    userId?: string;
+}
+export declare function scanPairsTool(args: ScanPairsArgs, deps: IntelApiDeps, decisionsDeps?: ScanPairsDecisionsDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;
+export declare const __testing__: {
+    resetCaches(): void;
+};