bitbank-lab-mcp 0.1.0

package/lib/indicators.ts

@@ -0,0 +1,579 @@
+/** Create a number[] of given length filled with NaN. */
+const nanArray = (len: number): number[] => Array.from<number>({ length: len }).fill(NaN);
+
+/**
+ * lib/indicators.ts - テクニカル指標の共通計算モジュール
+ *
+ * 全指標の純粋な計算関数を提供。
+ * リアルタイム分析 (tools/analyze_indicators.ts) と
+ * バックテストエンジン (tools/trading_process/) の両方から使用される。
+ *
+ * 【共通仕様】
+ * - 入力: number[]（古い順）
+ * - 出力: number[]（データ不足の位置は NaN）
+ * - 丸め処理なし（呼び出し元で必要に応じて丸める）
+ */
+
+/**
+ * 単純移動平均 (SMA)
+ *
+ * @param prices 価格配列（古い順）
+ * @param period 期間（正の整数）
+ * @returns SMA配列（先頭 period-1 個は NaN）
+ */
+export function sma(prices: number[], period: number): number[] {
+	if (period <= 0) {
+		throw new Error('SMA period must be positive');
+	}
+	if (prices.length < period) {
+		return nanArray(prices.length);
+	}
+
+	const result: number[] = nanArray(prices.length);
+
+	let sum = 0;
+	for (let i = 0; i < period; i++) {
+		sum += prices[i];
+	}
+	result[period - 1] = sum / period;
+
+	for (let i = period; i < prices.length; i++) {
+		sum = sum - prices[i - period] + prices[i];
+		result[i] = sum / period;
+	}
+
+	return result;
+}
+
+/**
+ * 指数移動平均 (EMA)
+ *
+ * 最初の EMA 値は period 区間の SMA をシードとして使用。
+ *
+ * @param prices 価格配列（古い順）
+ * @param period EMA 期間（2 以上）
+ * @returns EMA配列（先頭 period-1 個は NaN）
+ */
+export function ema(prices: number[], period: number): number[] {
+	const result: number[] = nanArray(prices.length);
+
+	if (prices.length < period || period < 1) {
+		return result;
+	}
+
+	// SMA をシードとする
+	let sum = 0;
+	for (let i = 0; i < period; i++) {
+		sum += prices[i];
+	}
+	result[period - 1] = sum / period;
+
+	const k = 2 / (period + 1);
+	for (let i = period; i < prices.length; i++) {
+		result[i] = prices[i] * k + result[i - 1] * (1 - k);
+	}
+
+	return result;
+}
+
+/**
+ * RSI (Relative Strength Index) — Wilder's Smoothing
+ *
+ * @param closes 終値配列（古い順）
+ * @param period RSI 期間（通常 14）
+ * @returns RSI配列（0–100、先頭 period 個は NaN）
+ */
+export function rsi(closes: number[], period: number): number[] {
+	const result: number[] = nanArray(closes.length);
+
+	if (closes.length < period + 1) {
+		return result;
+	}
+
+	// 価格変化
+	let avgGain = 0;
+	let avgLoss = 0;
+	for (let i = 1; i <= period; i++) {
+		const change = closes[i] - closes[i - 1];
+		if (change > 0) avgGain += change;
+		else avgLoss += Math.abs(change);
+	}
+	avgGain /= period;
+	avgLoss /= period;
+
+	// 最初の RSI
+	if (avgLoss === 0) {
+		result[period] = 100;
+	} else {
+		result[period] = 100 - 100 / (1 + avgGain / avgLoss);
+	}
+
+	// Wilder's Smoothing
+	for (let i = period + 1; i < closes.length; i++) {
+		const change = closes[i] - closes[i - 1];
+		const gain = change > 0 ? change : 0;
+		const loss = change < 0 ? Math.abs(change) : 0;
+
+		avgGain = (avgGain * (period - 1) + gain) / period;
+		avgLoss = (avgLoss * (period - 1) + loss) / period;
+
+		if (avgLoss === 0) {
+			result[i] = 100;
+		} else {
+			result[i] = 100 - 100 / (1 + avgGain / avgLoss);
+		}
+	}
+
+	return result;
+}
+
+/**
+ * NaN → null 変換 + オプショナル丸め。
+ * analyze_indicators.ts など NumericSeries を返す呼び出し元で使用。
+ *
+ * @param values number[]（NaN を含む）
+ * @param decimals 小数桁数（省略時は丸めなし）
+ * @returns (number | null)[]
+ */
+export function toNumericSeries(values: number[], decimals?: number): (number | null)[] {
+	return values.map((v) => {
+		if (!Number.isFinite(v)) return null;
+		return decimals != null ? Number(v.toFixed(decimals)) : v;
+	});
+}
+
+// ============================================================
+// Bollinger Bands
+// ============================================================
+
+/**
+ * ボリンジャーバンド
+ *
+ * @param values 価格配列（古い順）
+ * @param period SMA 期間（デフォルト 20）
+ * @param stdDev 標準偏差倍率（デフォルト 2）
+ * @returns { upper, middle, lower } — 各 number[]（先頭 period-1 個は NaN）
+ */
+export function bollingerBands(
+	values: number[],
+	period: number = 20,
+	stdDev: number = 2,
+): { upper: number[]; middle: number[]; lower: number[] } {
+	const n = values.length;
+	const upper: number[] = nanArray(n);
+	const middle: number[] = nanArray(n);
+	const lower: number[] = nanArray(n);
+
+	if (n < period) return { upper, middle, lower };
+
+	// 最初の window の合計
+	let sum = 0;
+	for (let i = 0; i < period; i++) sum += values[i];
+
+	for (let i = period - 1; i < n; i++) {
+		if (i > period - 1) {
+			sum = sum - values[i - period] + values[i];
+		}
+		const mean = sum / period;
+
+		let sumSq = 0;
+		for (let j = i - period + 1; j <= i; j++) {
+			sumSq += (values[j] - mean) ** 2;
+		}
+		const std = Math.sqrt(sumSq / period);
+
+		middle[i] = mean;
+		upper[i] = mean + stdDev * std;
+		lower[i] = mean - stdDev * std;
+	}
+
+	return { upper, middle, lower };
+}
+
+// ============================================================
+// MACD
+// ============================================================
+
+/**
+ * MACD (Moving Average Convergence Divergence)
+ *
+ * @param values 価格配列（古い順）
+ * @param fast 短期 EMA 期間（デフォルト 12）
+ * @param slow 長期 EMA 期間（デフォルト 26）
+ * @param signal シグナル EMA 期間（デフォルト 9）
+ * @returns { line, signal, hist } — 各 number[]（NaN で埋め）
+ */
+export function macd(
+	values: number[],
+	fast: number = 12,
+	slow: number = 26,
+	signal: number = 9,
+): { line: number[]; signal: number[]; hist: number[] } {
+	const emaFast = ema(values, fast);
+	const emaSlow = ema(values, slow);
+	const n = values.length;
+
+	// MACD line = fast EMA - slow EMA
+	const line: number[] = nanArray(n);
+	for (let i = 0; i < n; i++) {
+		if (!Number.isNaN(emaFast[i]) && !Number.isNaN(emaSlow[i])) {
+			line[i] = emaFast[i] - emaSlow[i];
+		}
+	}
+
+	// Signal EMA — 有効な MACD 値のみでシードする
+	const validStart = line.findIndex((v) => !Number.isNaN(v));
+	const signalLine: number[] = nanArray(n);
+
+	if (validStart >= 0) {
+		const validLine = line.slice(validStart).filter((v) => !Number.isNaN(v));
+		const sigEma = ema(validLine, signal);
+		let idx = 0;
+		for (let i = validStart; i < n; i++) {
+			if (!Number.isNaN(line[i])) {
+				signalLine[i] = sigEma[idx++];
+			}
+		}
+	}
+
+	// Histogram = line - signal
+	const hist: number[] = nanArray(n);
+	for (let i = 0; i < n; i++) {
+		if (!Number.isNaN(line[i]) && !Number.isNaN(signalLine[i])) {
+			hist[i] = line[i] - signalLine[i];
+		}
+	}
+
+	return { line, signal: signalLine, hist };
+}
+
+// ============================================================
+// Ichimoku Kinko Hyo
+// ============================================================
+
+/**
+ * 一目均衡表の時系列（全ライン）
+ *
+ * @returns { tenkan, kijun, spanA, spanB, chikou } — 各 number[]（NaN 埋め）
+ */
+export function ichimokuSeries(
+	highs: number[],
+	lows: number[],
+	closes: number[],
+): { tenkan: number[]; kijun: number[]; spanA: number[]; spanB: number[]; chikou: number[] } {
+	const n = highs.length;
+	const tenkan: number[] = nanArray(n);
+	const kijun: number[] = nanArray(n);
+	const spanA: number[] = nanArray(n);
+	const spanB: number[] = nanArray(n);
+
+	const tenkanP = 9;
+	const kijunP = 26;
+	const senkouBP = 52;
+
+	for (let i = 0; i < n; i++) {
+		if (i >= tenkanP - 1) {
+			const hSlice = highs.slice(i - tenkanP + 1, i + 1);
+			const lSlice = lows.slice(i - tenkanP + 1, i + 1);
+			tenkan[i] = (Math.max(...hSlice) + Math.min(...lSlice)) / 2;
+		}
+
+		if (i >= kijunP - 1) {
+			const hSlice = highs.slice(i - kijunP + 1, i + 1);
+			const lSlice = lows.slice(i - kijunP + 1, i + 1);
+			kijun[i] = (Math.max(...hSlice) + Math.min(...lSlice)) / 2;
+		}
+
+		if (!Number.isNaN(tenkan[i]) && !Number.isNaN(kijun[i])) {
+			spanA[i] = (tenkan[i] + kijun[i]) / 2;
+		}
+
+		if (i >= senkouBP - 1) {
+			const hSlice = highs.slice(i - senkouBP + 1, i + 1);
+			const lSlice = lows.slice(i - senkouBP + 1, i + 1);
+			spanB[i] = (Math.max(...hSlice) + Math.min(...lSlice)) / 2;
+		}
+	}
+
+	// chikou は終値そのまま（遅行スパンの位置シフトは呼び出し元で行う）
+	const chikou = closes.slice();
+
+	return { tenkan, kijun, spanA, spanB, chikou };
+}
+
+/**
+ * 遅行スパン（chikou）を 26 本過去方向にシフトした系列を返す。
+ *
+ * シフト後の系列長は元の系列長と同一。
+ * 末尾 `shift` 個は NaN（未来に対応するデータがないため）。
+ *
+ * @param chikou 終値配列（= ichimokuSeries().chikou）
+ * @param shift シフト量（デフォルト 26）
+ * @returns シフト適用済みの number[]（末尾 shift 個は NaN）
+ */
+export function shiftChikou(chikou: number[], shift: number = 26): number[] {
+	const n = chikou.length;
+	const result: number[] = nanArray(n);
+	for (let i = shift; i < n; i++) {
+		result[i - shift] = chikou[i];
+	}
+	return result;
+}
+
+/**
+ * 一目均衡表の最新スナップショット値
+ *
+ * @returns 最新の conversion/base/spanA/spanB、データ不足なら null
+ */
+export function ichimokuSnapshot(
+	highs: number[],
+	lows: number[],
+	_closes: number[],
+): { conversion: number; base: number; spanA: number; spanB: number } | null {
+	if (highs.length < 52 || lows.length < 52) return null;
+	const conversion = (Math.max(...highs.slice(-9)) + Math.min(...lows.slice(-9))) / 2;
+	const base = (Math.max(...highs.slice(-26)) + Math.min(...lows.slice(-26))) / 2;
+	const spanA = (conversion + base) / 2;
+	const spanB = (Math.max(...highs.slice(-52)) + Math.min(...lows.slice(-52))) / 2;
+	return { conversion, base, spanA, spanB };
+}
+
+// ============================================================
+// Classic Stochastic Oscillator
+// ============================================================
+
+/**
+ * クラシック・ストキャスティクス
+ *
+ * %K_raw = (Close - Low_n) / (High_n - Low_n) * 100
+ * %K = SMA(%K_raw, smoothK)
+ * %D = SMA(%K, smoothD)
+ *
+ * @returns { kSeries, dSeries } — 各 number[]（NaN 埋め）
+ */
+export function stochastic(
+	highs: number[],
+	lows: number[],
+	closes: number[],
+	kPeriod: number = 14,
+	smoothK: number = 3,
+	smoothD: number = 3,
+): { kSeries: number[]; dSeries: number[] } {
+	const n = Math.min(highs.length, lows.length, closes.length);
+	if (n < kPeriod + smoothK + smoothD - 2) {
+		return { kSeries: nanArray(n), dSeries: nanArray(n) };
+	}
+
+	// Raw %K
+	const rawK: number[] = nanArray(n);
+	for (let i = kPeriod - 1; i < n; i++) {
+		let hi = -Infinity;
+		let lo = Infinity;
+		for (let j = i - kPeriod + 1; j <= i; j++) {
+			if (highs[j] > hi) hi = highs[j];
+			if (lows[j] < lo) lo = lows[j];
+		}
+		const range = hi - lo;
+		rawK[i] = range === 0 ? 50 : ((closes[i] - lo) / range) * 100;
+	}
+
+	// %K = SMA(rawK, smoothK) — 手動ウィンドウ平均（NaN スキップ）
+	const kSeries: number[] = nanArray(n);
+	for (let i = 0; i < n; i++) {
+		if (Number.isNaN(rawK[i])) continue;
+		let sum = 0;
+		let cnt = 0;
+		for (let j = i - smoothK + 1; j <= i; j++) {
+			if (j >= 0 && !Number.isNaN(rawK[j])) {
+				sum += rawK[j];
+				cnt++;
+			}
+		}
+		if (cnt === smoothK) kSeries[i] = sum / cnt;
+	}
+
+	// %D = SMA(%K, smoothD)
+	const dSeries: number[] = nanArray(n);
+	for (let i = 0; i < n; i++) {
+		if (Number.isNaN(kSeries[i])) continue;
+		let sum = 0;
+		let cnt = 0;
+		for (let j = i - smoothD + 1; j <= i; j++) {
+			if (j >= 0 && !Number.isNaN(kSeries[j])) {
+				sum += kSeries[j];
+				cnt++;
+			}
+		}
+		if (cnt === smoothD) dSeries[i] = sum / cnt;
+	}
+
+	return { kSeries, dSeries };
+}
+
+// ============================================================
+// Stochastic RSI
+// ============================================================
+
+/**
+ * ストキャスティクス RSI
+ *
+ * RSI 値にストキャスティクス計算を適用。
+ *
+ * @returns { kSeries, dSeries } — 各 number[]（NaN 埋め）
+ */
+export function stochRSI(
+	closes: number[],
+	rsiPeriod: number = 14,
+	stochPeriod: number = 14,
+	smoothK: number = 3,
+	smoothD: number = 3,
+): { kSeries: number[]; dSeries: number[] } {
+	const rsiValues = rsi(closes, rsiPeriod);
+	const n = rsiValues.length;
+
+	const validCount = rsiValues.filter((v) => !Number.isNaN(v)).length;
+	if (validCount < stochPeriod + smoothK + smoothD) {
+		return { kSeries: nanArray(n), dSeries: nanArray(n) };
+	}
+
+	// Raw %K over RSI window
+	const rawK: number[] = nanArray(n);
+	for (let i = 0; i < n; i++) {
+		if (Number.isNaN(rsiValues[i]) || i < stochPeriod - 1) continue;
+		const window: number[] = [];
+		for (let j = i - stochPeriod + 1; j <= i; j++) {
+			if (!Number.isNaN(rsiValues[j])) window.push(rsiValues[j]);
+		}
+		if (window.length < stochPeriod) continue;
+		const lo = Math.min(...window);
+		const hi = Math.max(...window);
+		const range = hi - lo;
+		rawK[i] = range === 0 ? 50 : ((rsiValues[i] - lo) / range) * 100;
+	}
+
+	// Smooth rawK → %K
+	const kSeries: number[] = nanArray(n);
+	for (let i = 0; i < n; i++) {
+		if (Number.isNaN(rawK[i])) continue;
+		let sum = 0;
+		let cnt = 0;
+		for (let j = i - smoothK + 1; j <= i; j++) {
+			if (j >= 0 && !Number.isNaN(rawK[j])) {
+				sum += rawK[j];
+				cnt++;
+			}
+		}
+		if (cnt === smoothK) kSeries[i] = sum / cnt;
+	}
+
+	// %D = SMA(%K, smoothD)
+	const dSeries: number[] = nanArray(n);
+	for (let i = 0; i < n; i++) {
+		if (Number.isNaN(kSeries[i])) continue;
+		let sum = 0;
+		let cnt = 0;
+		for (let j = i - smoothD + 1; j <= i; j++) {
+			if (j >= 0 && !Number.isNaN(kSeries[j])) {
+				sum += kSeries[j];
+				cnt++;
+			}
+		}
+		if (cnt === smoothD) dSeries[i] = sum / cnt;
+	}
+
+	return { kSeries, dSeries };
+}
+
+// ============================================================
+// True Range / ATR
+// ============================================================
+
+/**
+ * True Range 系列
+ *
+ * TR = max(high - low, |high - prevClose|, |low - prevClose|)
+ *
+ * @param highs 高値配列（古い順）
+ * @param lows 安値配列（古い順）
+ * @param closes 終値配列（古い順）
+ * @returns TR 配列（先頭は NaN — prevClose が存在しない）
+ */
+export function trueRange(highs: number[], lows: number[], closes: number[]): number[] {
+	const n = Math.min(highs.length, lows.length, closes.length);
+	if (n < 2) return nanArray(n);
+
+	const result: number[] = nanArray(n);
+	for (let i = 1; i < n; i++) {
+		const h = highs[i];
+		const l = lows[i];
+		const pc = closes[i - 1];
+		if (!Number.isFinite(h) || !Number.isFinite(l) || !Number.isFinite(pc)) continue;
+		result[i] = Math.max(h - l, Math.abs(h - pc), Math.abs(l - pc));
+	}
+	return result;
+}
+
+/**
+ * ATR (Average True Range) — TR の SMA
+ *
+ * @param highs 高値配列（古い順）
+ * @param lows 安値配列（古い順）
+ * @param closes 終値配列（古い順）
+ * @param period 期間（デフォルト 14）
+ * @returns ATR 配列（NaN 埋め、先頭 period 個は NaN）
+ */
+export function atr(highs: number[], lows: number[], closes: number[], period: number = 14): number[] {
+	const tr = trueRange(highs, lows, closes);
+	const n = tr.length;
+	const result: number[] = nanArray(n);
+
+	if (n < period + 1) return result;
+
+	// TR[0] は NaN なので有効な TR は index 1 から
+	// 最初の ATR = SMA of TR[1..period]
+	let sum = 0;
+	for (let i = 1; i <= period; i++) {
+		if (Number.isNaN(tr[i])) return result;
+		sum += tr[i];
+	}
+	result[period] = sum / period;
+
+	// 以降は SMA スライディングウィンドウ
+	for (let i = period + 1; i < n; i++) {
+		if (Number.isNaN(tr[i])) continue;
+		sum = sum - tr[i - period] + tr[i];
+		result[i] = sum / period;
+	}
+
+	return result;
+}
+
+// ============================================================
+// OBV (On-Balance Volume)
+// ============================================================
+
+/**
+ * OBV（出来高累積指標）
+ *
+ * @param closes 終値配列（古い順）
+ * @param volumes 出来高配列（古い順）
+ * @returns OBV の累積配列（number[]）
+ */
+export function obv(closes: number[], volumes: number[]): number[] {
+	const n = Math.min(closes.length, volumes.length);
+	if (n < 1) return [];
+
+	const result: number[] = [0];
+	for (let i = 1; i < n; i++) {
+		const prev = result[i - 1];
+		if (closes[i] > closes[i - 1]) {
+			result.push(prev + volumes[i]);
+		} else if (closes[i] < closes[i - 1]) {
+			result.push(prev - volumes[i]);
+		} else {
+			result.push(prev);
+		}
+	}
+
+	return result;
+}

package/lib/logger.ts

@@ -0,0 +1,120 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { nowIso, today } from './datetime.js';
+
+const LOG_DIR = process.env.LOG_DIR || './logs';
+const LOG_LEVEL = (process.env.LOG_LEVEL || 'info').toLowerCase();
+const LEVELS: Record<string, number> = { error: 0, warn: 1, info: 2, debug: 3 };
+const THRESH = LEVELS[LOG_LEVEL] ?? LEVELS.info;
+
+function ensureDir(dir: string) {
+	if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeJsonl(file: string, obj: unknown) {
+	ensureDir(path.dirname(file));
+	fs.appendFileSync(file, `${JSON.stringify(obj)}\n`);
+}
+
+// ── チェーンハッシュ（取引操作ログ専用） ──
+
+let lastTradeHash = '0'.repeat(64);
+
+/** チェーンハッシュ付きで取引操作ログを書き込む */
+function writeTradeJsonl(file: string, record: Record<string, unknown>) {
+	ensureDir(path.dirname(file));
+	const withChain = { ...record, _prevHash: lastTradeHash };
+	const json = JSON.stringify(withChain);
+	lastTradeHash = createHash('sha256').update(json).digest('hex');
+	const finalRecord = { ...withChain, _hash: lastTradeHash };
+	fs.appendFileSync(file, `${JSON.stringify(finalRecord)}\n`);
+}
+
+export function log(level: 'error' | 'warn' | 'info' | 'debug', event: Record<string, unknown>): void {
+	if ((LEVELS[level] ?? 2) > THRESH) return;
+	const date = today('YYYY-MM-DD');
+	const file = path.join(LOG_DIR, `${date}.jsonl`);
+	const record = { ts: nowIso(), level, ...event } as const;
+	try {
+		writeJsonl(file, record);
+	} catch {
+		// best-effort: ignore log failures
+	}
+}
+
+/** ログ出力前に機密フィールドをマスクする */
+// 方針（残高・注文数量・価格）:
+// - SENSITIVE_KEYS は「認証・署名・確認トークン」系のみを対象とする。bitbank API キー／シークレット／
+//   confirmation_token のログ混入を防ぐのが主目的。
+// - balance / amount / price / free_amount 等はマスクしていない。ツール入力（例: create_order の amount）
+//   は maskSensitiveFields 後も数値文字列として jsonl に残り得る。これはサーバー管理者が MCP 利用者の
+//   操作監査・障害調査のためにローカルログを読む前提の設計であり、LOG_LEVEL=debug でも現状コードは
+//   `log('debug', …)` を呼ばない（閾値は THRESH のみ）。tool_run の result は ok/summary/meta のみで
+//   残高や約定一覧の data 本体は載せない。
+// - 取引操作の `logTradeAction` は amount/price を平文で含むが、改ざん検知用チェーンハッシュ付きの
+//   監査ログであり、集計・統計目的とは別レーンとして許容している。
+const SENSITIVE_KEYS = new Set(['confirmation_token', 'token', 'key', 'secret', 'apiKey', 'apiSecret']);
+
+function maskSensitiveFields(obj: unknown): unknown {
+	if (obj == null || typeof obj !== 'object') return obj;
+	if (Array.isArray(obj)) return obj.map(maskSensitiveFields);
+	const masked: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+		masked[key] = SENSITIVE_KEYS.has(key) && typeof value === 'string' ? '***' : maskSensitiveFields(value);
+	}
+	return masked;
+}
+
+export function logToolRun(args: { tool: string; input: unknown; result: unknown; ms: number }): void {
+	const { tool, input, result, ms } = args;
+	const r = result as Record<string, unknown> | null | undefined;
+	const safeData = {
+		ok: r?.ok,
+		summary: r?.summary,
+		meta: r?.meta,
+	};
+	log('info', { type: 'tool_run', tool, input: maskSensitiveFields(input), ms, result: safeData });
+}
+
+export function logError(tool: string, err: unknown, input: unknown): void {
+	log('error', {
+		type: 'tool_error',
+		tool,
+		input: maskSensitiveFields(input),
+		error: (err instanceof Error ? err.message : undefined) || String(err),
+	});
+}
+
+// ── 取引操作ログ（チェーンハッシュ付き） ──
+
+export function logTradeAction(action: {
+	type: 'create_order' | 'cancel_order' | 'cancel_orders';
+	orderId?: number;
+	orderIds?: number[];
+	pair: string;
+	side?: string;
+	orderType?: string;
+	amount?: string;
+	price?: string | null;
+	triggerPrice?: string | null;
+	positionSide?: string | null;
+	status: string;
+	confirmed: boolean;
+	/** どの経路から実行されたかの監査用ラベル（create_order / cancel_order / cancel_orders。二重発注や意図しないキャンセルの原因特定に使う） */
+	route?: 'elicitation' | 'ui-button' | 'direct-text';
+}) {
+	const date = today('YYYY-MM-DD');
+	const file = path.join(LOG_DIR, `${date}.jsonl`);
+	const record: Record<string, unknown> = {
+		ts: nowIso(),
+		level: 'info',
+		category: 'trade_action',
+		...action,
+	};
+	try {
+		writeTradeJsonl(file, record);
+	} catch {
+		// best-effort
+	}
+}