@reefclaw/openclaw-plugin 0.1.0

package/tools/get-sizing.js

@@ -0,0 +1,6 @@
+// Tool: get_sizing — fetches Half-Kelly position sizing recommendation from Intelligence API.
+// Returns recommended size as % of account, Kelly fraction, win rate, avg W/L ratio, vol adjustment.
+import { fetchIntelApi, enc } from './intel-api.js';
+export async function getSizingTool(args, deps) {
+    return fetchIntelApi(`/api/sizing/${enc(args.symbol)}`, deps);
+}

package/tools/get-trade-feedback.d.ts

@@ -0,0 +1,7 @@
+import type { IntelApiDeps } from './intel-api.js';
+export declare function getTradeFeedbackTool(args: {
+    symbol: string;
+    hours?: number;
+}, deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/get-trade-feedback.js

@@ -0,0 +1,8 @@
+// Tool: get_trade_feedback — fetches structured performance feedback from Intelligence API.
+// Returns per-setup-type win rates, regime breakdown, recent outcomes, and current streak.
+// Designed for the agent to review before entering trades.
+import { fetchIntelApi, enc } from './intel-api.js';
+export async function getTradeFeedbackTool(args, deps) {
+    const hours = args.hours ?? 168;
+    return fetchIntelApi(`/api/analytics/${enc(args.symbol)}/feedback?hours=${hours}`, deps);
+}

package/tools/get-trade-flow.d.ts

@@ -0,0 +1,7 @@
+import type { IntelApiDeps } from './intel-api.js';
+export declare function getTradeFlowTool(args: {
+    symbol: string;
+    minutes?: number;
+}, deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/get-trade-flow.js

@@ -0,0 +1,7 @@
+// Tool: get_trade_flow — fetches aggregated trade flow / institutional flow data.
+// Returns buy/sell volume, large trade (whale) activity, net delta, and whale pressure verdict.
+import { fetchIntelApi, enc } from './intel-api.js';
+export async function getTradeFlowTool(args, deps) {
+    const minutes = args.minutes ?? 5;
+    return fetchIntelApi(`/api/trade-flow/${enc(args.symbol)}?minutes=${minutes}`, deps);
+}

package/tools/get-volume-analysis.d.ts

@@ -0,0 +1,21 @@
+import type { BinancePublicApi } from '../ccxt/binance-public.js';
+export interface VolumeAnalysisResult {
+    symbol: string;
+    timeframe: string;
+    volumeExpansion: number;
+    closePosition: number;
+    directionalThrust: number;
+    buyVolEstimate: number;
+    latestVolume: number;
+    avgVolume: number;
+    interpretation: string;
+    timestamp: string;
+}
+export declare function getVolumeAnalysisTool(args: {
+    symbol: string;
+    timeframe?: string;
+}, deps: {
+    binanceApi: BinancePublicApi;
+}): Promise<VolumeAnalysisResult | {
+    error: string;
+}>;

package/tools/get-volume-analysis.js

@@ -0,0 +1,74 @@
+// Tool: get_volume_analysis — volume expansion, directional thrust, close position
+// Fetches 25 bars of 5m OHLCV and computes volume metrics for the latest bar.
+export async function getVolumeAnalysisTool(args, deps) {
+    const timeframe = args.timeframe ?? '5m';
+    try {
+        const candles = await deps.binanceApi.fetchOHLCV(args.symbol, timeframe, 25);
+        if (!candles || candles.length < 3) {
+            return { error: `Insufficient OHLCV data for ${args.symbol} ${timeframe}` };
+        }
+        // Filter valid bars (volume > 0)
+        const valid = candles.filter((c) => c[5] > 0);
+        if (valid.length < 3) {
+            return { error: `Insufficient valid bars for ${args.symbol} ${timeframe}` };
+        }
+        // Latest bar
+        const latest = valid[valid.length - 1];
+        const [, , latestHigh, latestLow, latestClose, latestVolume] = latest;
+        // 20-bar average volume (excluding latest bar)
+        const lookback = valid.slice(Math.max(0, valid.length - 21), valid.length - 1);
+        const avgVolume = lookback.length > 0
+            ? lookback.reduce((sum, r) => sum + r[5], 0) / lookback.length
+            : latestVolume;
+        // Volume expansion ratio
+        const volumeExpansion = avgVolume > 0 ? latestVolume / avgVolume : 1;
+        // Close position: where close sits in the bar's range (0 = low, 1 = high)
+        const range = latestHigh - latestLow;
+        const closePosition = range > 0 ? (latestClose - latestLow) / range : 0.5;
+        // Directional thrust: combines volume expansion with close position
+        // -1 = high volume bearish (close at low), +1 = high volume bullish (close at high)
+        const dirMultiplier = (closePosition - 0.5) * 2;
+        const cappedExpansion = Math.min(volumeExpansion, 5);
+        const directionalThrust = dirMultiplier * Math.min(1, cappedExpansion / 2);
+        // Buy volume estimate (proxy)
+        const buyVolEstimate = closePosition;
+        // Human-readable interpretation
+        let interpretation;
+        if (volumeExpansion > 2 && directionalThrust > 0.3) {
+            interpretation = 'Strong bullish volume surge — buyers aggressive';
+        }
+        else if (volumeExpansion > 2 && directionalThrust < -0.3) {
+            interpretation = 'Strong bearish volume surge — sellers aggressive';
+        }
+        else if (volumeExpansion > 1.5 && Math.abs(directionalThrust) < 0.15) {
+            interpretation = 'High volume indecision — battle between buyers and sellers';
+        }
+        else if (volumeExpansion < 0.5) {
+            interpretation = 'Low volume — lack of participation, potential breakout setup';
+        }
+        else if (directionalThrust > 0.2) {
+            interpretation = 'Moderate bullish bias — close near highs';
+        }
+        else if (directionalThrust < -0.2) {
+            interpretation = 'Moderate bearish bias — close near lows';
+        }
+        else {
+            interpretation = 'Normal volume, neutral positioning';
+        }
+        return {
+            symbol: args.symbol,
+            timeframe,
+            volumeExpansion: +volumeExpansion.toFixed(2),
+            closePosition: +closePosition.toFixed(3),
+            directionalThrust: +directionalThrust.toFixed(3),
+            buyVolEstimate: +buyVolEstimate.toFixed(3),
+            latestVolume: Math.round(latestVolume),
+            avgVolume: Math.round(avgVolume),
+            interpretation,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    catch (err) {
+        return { error: `get_volume_analysis failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}

package/tools/get-volume-profile.d.ts

@@ -0,0 +1,7 @@
+import type { IntelApiDeps } from './intel-api.js';
+export declare function getVolumeProfileTool(args: {
+    symbol: string;
+    period?: number;
+}, deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/get-volume-profile.js

@@ -0,0 +1,7 @@
+// Tool: get_volume_profile — fetches volume profile from the Intelligence API.
+// Returns price buckets with buy/sell volume, POC, value area, and current price.
+import { fetchIntelApi, enc } from './intel-api.js';
+export async function getVolumeProfileTool(args, deps) {
+    const period = args.period ?? 24;
+    return fetchIntelApi(`/api/volume-profile/${enc(args.symbol)}?period=${period}`, deps);
+}

package/tools/helpers.d.ts

@@ -0,0 +1,25 @@
+import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { ExchangeSimulator } from '../simulator/exchange-simulator.js';
+import type { CcxtTicker } from '../types.js';
+/**
+ * Fetch the latest ticker from Binance and update the simulator.
+ * Returns the ticker on success, or an error object on failure.
+ */
+export declare function fetchCurrentPrice(symbol: string, deps: {
+    binanceApi: BinancePublicApi;
+    simulator: ExchangeSimulator;
+}): Promise<CcxtTicker | {
+    error: string;
+}>;
+/**
+ * Fetch the latest order book from Binance and cache in simulator.
+ * Best-effort: never throws. Skips fetch if cached book is fresh enough.
+ */
+export declare function fetchOrderBook(symbol: string, deps: {
+    binanceApi: BinancePublicApi;
+    simulator: ExchangeSimulator;
+}): Promise<void>;
+/** Type guard: check if the result is an error object */
+export declare function isError(result: unknown): result is {
+    error: string;
+};

package/tools/helpers.js

@@ -0,0 +1,38 @@
+// Shared helpers for tool implementations.
+/**
+ * Fetch the latest ticker from Binance and update the simulator.
+ * Returns the ticker on success, or an error object on failure.
+ */
+export async function fetchCurrentPrice(symbol, deps) {
+    const ticker = await deps.binanceApi.fetchTicker(symbol);
+    if (!ticker) {
+        return { error: `Failed to fetch current price for ${symbol}` };
+    }
+    deps.simulator.updateTicker(ticker);
+    return ticker;
+}
+/** Default TTL for cached orderbook: 5 seconds. */
+const ORDERBOOK_TTL_MS = 5_000;
+/**
+ * Fetch the latest order book from Binance and cache in simulator.
+ * Best-effort: never throws. Skips fetch if cached book is fresh enough.
+ */
+export async function fetchOrderBook(symbol, deps) {
+    try {
+        // Skip if cached book is still fresh
+        const cached = deps.simulator.getLastOrderBook(symbol);
+        if (cached && Date.now() - cached.timestamp < ORDERBOOK_TTL_MS)
+            return;
+        const orderbook = await deps.binanceApi.fetchOrderBook(symbol, 20);
+        if (orderbook) {
+            deps.simulator.updateOrderBook(symbol, orderbook);
+        }
+    }
+    catch {
+        // Best-effort: fill engine falls back to random slippage
+    }
+}
+/** Type guard: check if the result is an error object */
+export function isError(result) {
+    return typeof result === 'object' && result !== null && 'error' in result;
+}

package/tools/intel-api.d.ts

@@ -0,0 +1,14 @@
+export interface IntelApiDeps {
+    connectionToken: string;
+    intelligenceUrl: string;
+}
+export interface FetchOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    body?: unknown;
+    timeoutMs?: number;
+}
+/** Encode a value for safe use in a URL path segment */
+export declare const enc: typeof encodeURIComponent;
+export declare function fetchIntelApi(path: string, deps: IntelApiDeps, options?: FetchOptions): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/intel-api.js

@@ -0,0 +1,52 @@
+// Shared helper for Intelligence API calls.
+// All intelligence tools use Bearer token auth against intel.reefclaw.com.
+/** Encode a value for safe use in a URL path segment */
+export const enc = encodeURIComponent;
+export async function fetchIntelApi(path, deps, options) {
+    const { connectionToken, intelligenceUrl } = deps;
+    if (!connectionToken) {
+        return { error: 'No ReefClaw connection token configured. Intelligence features require a reefclaw.com account.' };
+    }
+    if (!intelligenceUrl) {
+        return { error: 'No intelligence URL configured. Set intelligenceUrl in openclaw.json plugin config.' };
+    }
+    const url = `${intelligenceUrl}${path}`;
+    const headers = { Authorization: `Bearer ${connectionToken}` };
+    const fetchInit = {
+        method: options?.method ?? 'GET',
+        headers,
+        signal: AbortSignal.timeout(options?.timeoutMs ?? 20_000),
+    };
+    if (options?.body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+        fetchInit.body = JSON.stringify(options.body);
+    }
+    try {
+        const res = await fetch(url, fetchInit);
+        if (res.status === 401) {
+            return { error: 'Invalid or expired ReefClaw connection token.' };
+        }
+        if (res.status === 503) {
+            return { error: 'Intelligence service not ready. The regime classifier may still be loading.' };
+        }
+        if (!res.ok) {
+            // Try to extract the server's error message for actionable feedback
+            let detail = `Intelligence API returned ${res.status}`;
+            try {
+                const errBody = (await res.json());
+                if (errBody.error)
+                    detail = errBody.error;
+            }
+            catch { /* ignore parse failures */ }
+            return { error: detail };
+        }
+        return (await res.json());
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'TimeoutError') {
+            const timeoutSec = Math.round((options?.timeoutMs ?? 20_000) / 1000);
+            return { error: `Intelligence API request timed out (${timeoutSec}s). Try again later.` };
+        }
+        return { error: `Intelligence API call failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}

package/tools/intel-cache.d.ts

@@ -0,0 +1,25 @@
+import type { IntelApiDeps } from './intel-api.js';
+import type { SymbolFact, StrategyConfig, StrategyRow } from '../strategy/evaluator.js';
+export declare function getAllFactsCached(deps: IntelApiDeps): Promise<SymbolFact[] | {
+    error: string;
+}>;
+/** Look up a single symbol's fact, preferring the shared all-facts snapshot.
+ *  Falls back to the single-symbol endpoint when the all-facts snapshot is
+ *  cold or the symbol is missing from it (e.g., a watchlist symbol not in
+ *  the default 20-pair set). */
+export declare function getFactBySymbolCached(rawSymbol: string, deps: IntelApiDeps): Promise<SymbolFact | {
+    error: string;
+}>;
+/** Fetch active strategy rows, caching the full row shape. Both
+ *  getStrategiesCached and this share the same rows cache so a warm cache
+ *  from either entry point services the other without a second fetch. */
+export declare function getStrategyRowsCached(deps: IntelApiDeps): Promise<StrategyRow[] | {
+    error: string;
+}>;
+/** Backwards-compatible configs-only view, derived from the rows cache. */
+export declare function getStrategiesCached(deps: IntelApiDeps): Promise<StrategyConfig[] | {
+    error: string;
+}>;
+export declare const __testing__: {
+    resetCaches(): void;
+};

package/tools/intel-cache.js

@@ -0,0 +1,133 @@
+// Shared TTL cache for intelligence facts + strategies.
+//
+// Why this module exists: scan_pairs and get_setup_detail used to maintain
+// independent caches. scan_pairs cached the all-facts endpoint with a 30s
+// TTL; get_setup_detail had no cache and hit the single-symbol endpoint on
+// every call. When the fact-computer recomputed between the two calls,
+// scan_pairs and get_setup_detail saw different facts for the same symbol —
+// regime, chosen strategy, and entry/stop geometry could all diverge. The
+// 2026-05-15 session showed this repeatedly: scan ranks AVAX as TREND_DOWN
+// short, drill-down returns a LONG ladder, agent rejects setup as
+// "directionally inconsistent." Sharing the cache eliminates the divergence.
+//
+// API:
+//   getAllFactsCached(deps)               — populates the all-facts cache
+//   getFactBySymbolCached(symbol, deps)   — reads from all-facts cache when
+//                                            warm; otherwise falls back to
+//                                            single-symbol fetch + populates
+//                                            per-symbol cache
+//   getStrategiesCached(deps)             — strategies cache
+//   __testing__.resetCaches()             — clears all caches between tests
+import { fetchIntelApi, enc } from './intel-api.js';
+// facts refresh every 5 min server-side; 30s client cache is safe
+const FACTS_TTL_MS = 30_000;
+// strategies are slow-changing user state
+const STRAT_TTL_MS = 60_000;
+let allFactsCache = null;
+// Single rows cache backs BOTH the configs-only and rows views — keeping them
+// independent caused divergent fetches (scan_pairs warmed configs but
+// get_setup_detail's rows lookup missed and re-fetched, returning undefined
+// on test mocks). One cache, two derived views.
+let stratRowCache = null;
+// per-symbol cache for cases where the all-facts cache hasn't been populated
+// in this heartbeat (e.g., the agent called get_setup_detail directly without
+// running scan_pairs first).
+const symbolFactCache = new Map();
+function normalizeSymbol(raw) {
+    return raw.toUpperCase().replace(/[^A-Z0-9]/g, '');
+}
+export async function getAllFactsCached(deps) {
+    const now = Date.now();
+    if (allFactsCache && now < allFactsCache.expiry)
+        return allFactsCache.value;
+    const resp = await fetchIntelApi('/api/facts', deps, { timeoutMs: 30_000 });
+    if (!resp || typeof resp !== 'object') {
+        return { error: 'Intelligence /api/facts returned no response.' };
+    }
+    if ('error' in resp)
+        return { error: resp.error };
+    const value = (resp.facts ?? []);
+    allFactsCache = { value, expiry: now + FACTS_TTL_MS };
+    // Seed the per-symbol cache so a subsequent getFactBySymbolCached call
+    // for any symbol in this snapshot hits a cache without a round-trip.
+    const seedExpiry = now + FACTS_TTL_MS;
+    for (const f of value) {
+        if (!f.symbol)
+            continue;
+        symbolFactCache.set(normalizeSymbol(f.symbol), { value: f, expiry: seedExpiry });
+    }
+    return value;
+}
+/** Look up a single symbol's fact, preferring the shared all-facts snapshot.
+ *  Falls back to the single-symbol endpoint when the all-facts snapshot is
+ *  cold or the symbol is missing from it (e.g., a watchlist symbol not in
+ *  the default 20-pair set). */
+export async function getFactBySymbolCached(rawSymbol, deps) {
+    const symbol = normalizeSymbol(rawSymbol);
+    const now = Date.now();
+    // 1. Try the per-symbol cache (seeded by getAllFactsCached or by a prior
+    //    single-symbol fetch).
+    const cached = symbolFactCache.get(symbol);
+    if (cached && now < cached.expiry)
+        return cached.value;
+    // 2. If the all-facts cache is warm and contains the symbol, use it. This
+    //    is the path that closes the scan_pairs / get_setup_detail divergence —
+    //    after a heartbeat scan, every drill-down hits the same snapshot the
+    //    scan saw.
+    if (allFactsCache && now < allFactsCache.expiry) {
+        const hit = allFactsCache.value.find(f => normalizeSymbol(f.symbol) === symbol);
+        if (hit) {
+            symbolFactCache.set(symbol, { value: hit, expiry: allFactsCache.expiry });
+            return hit;
+        }
+    }
+    // 3. Fall back to the single-symbol endpoint (symbol not in default scan
+    //    set, or both caches cold). Populate the per-symbol cache so a repeat
+    //    call in the same heartbeat is free.
+    const resp = await fetchIntelApi(`/api/facts/${enc(symbol)}`, deps, { timeoutMs: 30_000 });
+    if (!resp || typeof resp !== 'object') {
+        return { error: `Intelligence /api/facts/${symbol} returned no response.` };
+    }
+    if ('error' in resp)
+        return { error: resp.error };
+    const fact = resp;
+    if (!fact.symbol) {
+        return { error: `No facts available for ${symbol}` };
+    }
+    symbolFactCache.set(symbol, { value: fact, expiry: now + FACTS_TTL_MS });
+    return fact;
+}
+/** Fetch active strategy rows, caching the full row shape. Both
+ *  getStrategiesCached and this share the same rows cache so a warm cache
+ *  from either entry point services the other without a second fetch. */
+export async function getStrategyRowsCached(deps) {
+    const now = Date.now();
+    if (stratRowCache && now < stratRowCache.expiry)
+        return stratRowCache.value;
+    const resp = await fetchIntelApi('/api/strategies?active=true', deps, { timeoutMs: 20_000 });
+    // The mocked fetch may return undefined when no more responses are queued;
+    // guard explicitly rather than relying on `'error' in resp` (the `in`
+    // operator throws on undefined).
+    if (!resp || typeof resp !== 'object') {
+        return { error: 'Intelligence /api/strategies returned no response.' };
+    }
+    if ('error' in resp)
+        return { error: resp.error };
+    const rows = (resp.strategies ?? []);
+    stratRowCache = { value: rows, expiry: now + STRAT_TTL_MS };
+    return rows;
+}
+/** Backwards-compatible configs-only view, derived from the rows cache. */
+export async function getStrategiesCached(deps) {
+    const rows = await getStrategyRowsCached(deps);
+    if ('error' in rows)
+        return rows;
+    return rows.map(r => r.config);
+}
+export const __testing__ = {
+    resetCaches() {
+        allFactsCache = null;
+        stratRowCache = null;
+        symbolFactCache.clear();
+    },
+};

package/tools/list-strategies.d.ts

@@ -0,0 +1,7 @@
+import type { IntelApiDeps } from './intel-api.js';
+export interface ListStrategiesArgs {
+    active_only?: boolean;
+}
+export declare function listStrategiesTool(args: ListStrategiesArgs, deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/list-strategies.js

@@ -0,0 +1,6 @@
+// Tool: list_strategies — list all strategies in the Strategy Box.
+import { fetchIntelApi } from './intel-api.js';
+export async function listStrategiesTool(args, deps) {
+    const query = args.active_only ? '?active=true' : '';
+    return fetchIntelApi(`/api/strategies${query}`, deps);
+}

package/tools/modify-stop.d.ts

@@ -0,0 +1,17 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+interface ModifyStopArgs {
+    symbol: string;
+    new_stop_price: number;
+}
+interface ModifyStopResult {
+    ok: true;
+    symbol: string;
+    old_stop_price: number | null;
+    new_stop_price: number;
+}
+export declare function modifyStopTool(args: ModifyStopArgs, deps: {
+    adapter: IExchangeAdapter;
+}): Promise<ModifyStopResult | {
+    error: string;
+}>;
+export {};

package/tools/modify-stop.js

@@ -0,0 +1,81 @@
+// Tool: modify_stop — move the exchange-side stop-loss on an open live
+// position. Implemented as cancel-then-resubmit inside BracketManager, with
+// automatic rollback if the new submit fails.
+//
+// Paper mode: moves the position's metadata.stopPrice in place (the paper
+// stop-watcher reads it), so BE/trail works without a close+reopen round-trip.
+// Live mode without brackets enabled: error asking operator to enable.
+import { validateStopDirection } from '../live/bracket-params.js';
+import { formatError } from '../logger.js';
+export async function modifyStopTool(args, deps) {
+    if (!args.symbol)
+        return { error: 'symbol is required.' };
+    if (!Number.isFinite(args.new_stop_price) || args.new_stop_price <= 0) {
+        return { error: 'new_stop_price must be a positive number.' };
+    }
+    if (!deps.adapter.isLive) {
+        return modifyStopPaper(deps.adapter, args);
+    }
+    const mgr = deps.adapter.getBracketManager?.();
+    const ledger = deps.adapter.getBracketLedger?.();
+    if (!mgr || !ledger) {
+        return { error: 'Bracket orders are not enabled. Set brackets.mode in plugin-config.json to "observe" or "enforce".' };
+    }
+    const entry = ledger.getBySymbol(args.symbol);
+    if (!entry) {
+        return { error: `No active bracket for ${args.symbol}.` };
+    }
+    // Direction check — catch flipped sign before burning a cancel+resubmit cycle
+    const refPrice = entry.stopPrice && entry.targetPrice
+        ? (entry.stopPrice + entry.targetPrice) / 2
+        : await deps.adapter.getLastPrice(args.symbol);
+    if (refPrice != null && refPrice > 0) {
+        const msg = validateStopDirection(entry.entrySide, refPrice, args.new_stop_price);
+        if (msg)
+            return { error: msg };
+    }
+    try {
+        await mgr.modifyStop(args.symbol, args.new_stop_price);
+        return {
+            ok: true,
+            symbol: args.symbol,
+            old_stop_price: entry.stopPrice ?? null,
+            new_stop_price: args.new_stop_price,
+        };
+    }
+    catch (err) {
+        return { error: formatError(err) };
+    }
+}
+/** Paper: move the stop on the open position's metadata in place. Validates the
+ *  same direction geometry live does (stop on the losing side of the current
+ *  mark), then writes metadata.stopPrice — no fee, no entry/R reset. */
+function modifyStopPaper(adapter, args) {
+    const sim = adapter.getSimulator();
+    const pos = sim.getPositions(args.symbol)[0];
+    if (!pos) {
+        return { error: `No open position for ${args.symbol}.` };
+    }
+    // Validate against the current mark (permits breakeven / trailing — the stop
+    // just has to stay on the losing side of where price is now).
+    const refPrice = pos.markPrice;
+    const entrySide = pos.side === 'long' ? 'buy' : 'sell';
+    if (Number.isFinite(refPrice) && refPrice > 0) {
+        const msg = validateStopDirection(entrySide, refPrice, args.new_stop_price);
+        if (msg)
+            return { error: msg };
+    }
+    const oldStop = pos.stopPrice ?? null;
+    try {
+        sim.updatePositionMetadata(args.symbol, { stopPrice: args.new_stop_price });
+    }
+    catch (err) {
+        return { error: formatError(err) };
+    }
+    return {
+        ok: true,
+        symbol: args.symbol,
+        old_stop_price: oldStop,
+        new_stop_price: args.new_stop_price,
+    };
+}

package/tools/modify-target.d.ts

@@ -0,0 +1,17 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+interface ModifyTargetArgs {
+    symbol: string;
+    new_target_price: number;
+}
+interface ModifyTargetResult {
+    ok: true;
+    symbol: string;
+    old_target_price: number | null;
+    new_target_price: number;
+}
+export declare function modifyTargetTool(args: ModifyTargetArgs, deps: {
+    adapter: IExchangeAdapter;
+}): Promise<ModifyTargetResult | {
+    error: string;
+}>;
+export {};

package/tools/modify-target.js

@@ -0,0 +1,71 @@
+// Tool: modify_target — move the exchange-side take-profit on an open live
+// position. Mirror of modify_stop; see that file for rationale.
+import { validateTargetDirection } from '../live/bracket-params.js';
+import { formatError } from '../logger.js';
+export async function modifyTargetTool(args, deps) {
+    if (!args.symbol)
+        return { error: 'symbol is required.' };
+    if (!Number.isFinite(args.new_target_price) || args.new_target_price <= 0) {
+        return { error: 'new_target_price must be a positive number.' };
+    }
+    if (!deps.adapter.isLive) {
+        return modifyTargetPaper(deps.adapter, args);
+    }
+    const mgr = deps.adapter.getBracketManager?.();
+    const ledger = deps.adapter.getBracketLedger?.();
+    if (!mgr || !ledger) {
+        return { error: 'Bracket orders are not enabled. Set brackets.mode in plugin-config.json to "observe" or "enforce".' };
+    }
+    const entry = ledger.getBySymbol(args.symbol);
+    if (!entry) {
+        return { error: `No active bracket for ${args.symbol}.` };
+    }
+    const refPrice = entry.stopPrice && entry.targetPrice
+        ? (entry.stopPrice + entry.targetPrice) / 2
+        : await deps.adapter.getLastPrice(args.symbol);
+    if (refPrice != null && refPrice > 0) {
+        const msg = validateTargetDirection(entry.entrySide, refPrice, args.new_target_price);
+        if (msg)
+            return { error: msg };
+    }
+    try {
+        await mgr.modifyTarget(args.symbol, args.new_target_price);
+        return {
+            ok: true,
+            symbol: args.symbol,
+            old_target_price: entry.targetPrice ?? null,
+            new_target_price: args.new_target_price,
+        };
+    }
+    catch (err) {
+        return { error: formatError(err) };
+    }
+}
+/** Paper: move the take-profit on the open position's metadata in place. */
+function modifyTargetPaper(adapter, args) {
+    const sim = adapter.getSimulator();
+    const pos = sim.getPositions(args.symbol)[0];
+    if (!pos) {
+        return { error: `No open position for ${args.symbol}.` };
+    }
+    const refPrice = pos.markPrice;
+    const entrySide = pos.side === 'long' ? 'buy' : 'sell';
+    if (Number.isFinite(refPrice) && refPrice > 0) {
+        const msg = validateTargetDirection(entrySide, refPrice, args.new_target_price);
+        if (msg)
+            return { error: msg };
+    }
+    const oldTarget = pos.targetPrice ?? null;
+    try {
+        sim.updatePositionMetadata(args.symbol, { targetPrice: args.new_target_price });
+    }
+    catch (err) {
+        return { error: formatError(err) };
+    }
+    return {
+        ok: true,
+        symbol: args.symbol,
+        old_target_price: oldTarget,
+        new_target_price: args.new_target_price,
+    };
+}