@zhive/cli 0.6.7 → 0.6.9

package/dist/shared/agent/tools/market/tools.js

@@ -1,24 +1,9 @@
 import { tool } from 'ai';
 import { z } from 'zod';
-import { getMarketClient } from './client.js';
-import { computeSMA, computeEMA, computeRSI, computeMACD, computeBollingerBands, } from '../ta/indicators.js';
-import { formatToolError, signPrefix, truncateTimeseries, truncationLabel } from '../formatting.js';
-/**
- * Adjusts the 'from' date backwards to ensure sufficient data points are fetched
- * for indicator calculation. Adds a 30% buffer for weekends/gaps in data.
- */
-function adjustFromDate(from, minPoints, interval) {
-    const fromDate = new Date(from);
-    const buffer = Math.ceil(minPoints * 0.3);
-    const totalPoints = minPoints + buffer;
-    if (interval === 'hourly') {
-        fromDate.setTime(fromDate.getTime() - totalPoints * 60 * 60 * 1000);
-    }
-    else {
-        fromDate.setTime(fromDate.getTime() - totalPoints * 24 * 60 * 60 * 1000);
-    }
-    return fromDate.toISOString();
-}
+import { InsufficientDataError } from '../../../ta/error.js';
+import { getBollingerBands, getEMA, getMACD, getOHLC, getPrice, getRSI, getSMA, } from '../../../ta/service.js';
+import { formatBollingerData, formatIndicatorData, formatMACDData, formatOhlcData, } from './utils.js';
+import { formatToolError } from '../../utils.js';
 const timeRangeSchema = z.object({
     from: z
         .string()
@@ -39,23 +24,13 @@ export const getPriceTool = tool({
             .describe('Optional timestamp in ISO 8601 format. If omitted, returns the current price.'),
     }),
     execute: async ({ projectId, timestamp }) => {
+        const effectiveTimestamp = timestamp ?? new Date().toISOString();
         try {
-            const effectiveTimestamp = timestamp ?? new Date().toISOString();
-            const client = getMarketClient();
-            const priceData = await client.getPrice(projectId, effectiveTimestamp);
-            if (priceData.price === null) {
+            const price = await getPrice({ project: projectId, at: effectiveTimestamp });
+            if (price === undefined) {
                 return `No price data available for ${projectId} at ${effectiveTimestamp}.`;
             }
-            const price = priceData.price;
-            const priceFormatted = price.toLocaleString('en-US', {
-                style: 'currency',
-                currency: 'USD',
-                minimumFractionDigits: 2,
-                maximumFractionDigits: price < 1 ? 6 : 2,
-            });
-            const timeLabel = timestamp ? `at ${timestamp}` : '(current)';
-            const output = `${projectId}: ${priceFormatted} ${timeLabel}`;
-            return output;
+            return price;
         }
         catch (err) {
             return formatToolError(err, 'fetching price');
@@ -74,38 +49,17 @@ export const getOHLCTool = tool({
     }),
     execute: async ({ id, from, to, interval }) => {
         try {
-            const client = getMarketClient();
             const effectiveInterval = interval ?? 'daily';
-            const ohlcData = await client.getOHLC(id, from, to, effectiveInterval);
+            const ohlcData = await getOHLC({
+                project: id,
+                from,
+                to,
+                interval: effectiveInterval,
+            });
             if (ohlcData.length === 0) {
                 return `No OHLC data available for ${id} from ${from} to ${to}.`;
             }
-            const lines = [
-                `OHLC data for ${id} (${effectiveInterval}, ${ohlcData.length} data points):`,
-                '',
-                'Date | Open | High | Low | Close',
-                '--- | --- | --- | --- | ---',
-            ];
-            const displayData = truncateTimeseries(ohlcData, 30, 10, 10);
-            for (const point of displayData) {
-                if (point === null) {
-                    lines.push(truncationLabel(ohlcData.length, 20));
-                    continue;
-                }
-                const date = new Date(point[0]).toISOString().split('T')[0];
-                const open = point[1].toFixed(2);
-                const high = point[2].toFixed(2);
-                const low = point[3].toFixed(2);
-                const close = point[4].toFixed(2);
-                lines.push(`${date} | $${open} | $${high} | $${low} | $${close}`);
-            }
-            const firstClose = ohlcData[0][4];
-            const lastClose = ohlcData[ohlcData.length - 1][4];
-            const changePercent = ((lastClose - firstClose) / firstClose) * 100;
-            lines.push('');
-            lines.push(`Period change: ${signPrefix(changePercent)}${changePercent.toFixed(2)}% ($${firstClose.toFixed(2)} → $${lastClose.toFixed(2)})`);
-            const output = lines.join('\n');
-            return output;
+            return formatOhlcData(ohlcData);
         }
         catch (err) {
             return formatToolError(err, 'fetching OHLC data');
@@ -130,42 +84,20 @@ export const getSMATool = tool({
     }),
     execute: async ({ id, period, from, to, interval }) => {
         try {
-            const client = getMarketClient();
-            const effectiveInterval = interval ?? 'daily';
-            const adjustedFrom = adjustFromDate(from, period, effectiveInterval);
-            const ohlcData = await client.getOHLC(id, adjustedFrom, to, effectiveInterval);
-            if (ohlcData.length < period) {
-                return `Insufficient data: got ${ohlcData.length} data points but need at least ${period} for SMA-${period}.`;
-            }
-            const smaData = computeSMA(ohlcData, period);
-            if (smaData.length === 0) {
-                return `Could not compute SMA-${period} for ${id}.`;
-            }
-            // Filter results to original date range
-            const originalFromTime = new Date(from).getTime();
-            const filteredData = smaData.filter((point) => point.timestamp >= originalFromTime);
-            if (filteredData.length === 0) {
-                return `No SMA-${period} data available within the requested date range for ${id}.`;
-            }
-            const lines = [
-                `SMA-${period} for ${id} (${effectiveInterval}, ${filteredData.length} values):`,
-                '',
-            ];
-            for (const point of filteredData) {
-                const date = new Date(point.timestamp).toISOString().split('T')[0];
-                lines.push(`${date}: $${point.value.toFixed(2)}`);
-            }
-            const latestSMA = filteredData[filteredData.length - 1].value;
-            const latestPrice = ohlcData[ohlcData.length - 1][4];
-            const aboveBelow = latestPrice > latestSMA ? 'above' : 'below';
-            const diff = ((latestPrice - latestSMA) / latestSMA) * 100;
-            lines.push('');
-            lines.push(`Current price ($${latestPrice.toFixed(2)}) is ${aboveBelow} SMA-${period} ($${latestSMA.toFixed(2)}) by ${signPrefix(diff)}${diff.toFixed(2)}%`);
-            const output = lines.join('\n');
-            return output;
+            const smaResult = await getSMA({
+                project: id,
+                interval,
+                from,
+                to,
+                period,
+            });
+            return formatIndicatorData(smaResult);
         }
-        catch (err) {
-            return formatToolError(err, 'calculating SMA');
+        catch (e) {
+            if (e instanceof InsufficientDataError) {
+                return `Insufficient data: got ${e.got} data points but need at least ${e.required} for SMA${period}.`;
+            }
+            return formatToolError(e, 'calculating SMA');
         }
     },
 });
@@ -187,42 +119,20 @@ export const getEMATool = tool({
     }),
     execute: async ({ id, period, from, to, interval }) => {
         try {
-            const client = getMarketClient();
-            const effectiveInterval = interval ?? 'daily';
-            const adjustedFrom = adjustFromDate(from, period, effectiveInterval);
-            const ohlcData = await client.getOHLC(id, adjustedFrom, to, effectiveInterval);
-            if (ohlcData.length < period) {
-                return `Insufficient data: got ${ohlcData.length} data points but need at least ${period} for EMA-${period}.`;
-            }
-            const emaData = computeEMA(ohlcData, period);
-            if (emaData.length === 0) {
-                return `Could not compute EMA-${period} for ${id}.`;
-            }
-            // Filter results to original date range
-            const originalFromTime = new Date(from).getTime();
-            const filteredData = emaData.filter((point) => point.timestamp >= originalFromTime);
-            if (filteredData.length === 0) {
-                return `No EMA-${period} data available within the requested date range for ${id}.`;
-            }
-            const lines = [
-                `EMA-${period} for ${id} (${effectiveInterval}, ${filteredData.length} values):`,
-                '',
-            ];
-            for (const point of filteredData) {
-                const date = new Date(point.timestamp).toISOString().split('T')[0];
-                lines.push(`${date}: $${point.value.toFixed(2)}`);
-            }
-            const latestEMA = filteredData[filteredData.length - 1].value;
-            const latestPrice = ohlcData[ohlcData.length - 1][4];
-            const aboveBelow = latestPrice > latestEMA ? 'above' : 'below';
-            const diff = ((latestPrice - latestEMA) / latestEMA) * 100;
-            lines.push('');
-            lines.push(`Current price ($${latestPrice.toFixed(2)}) is ${aboveBelow} EMA-${period} ($${latestEMA.toFixed(2)}) by ${signPrefix(diff)}${diff.toFixed(2)}%`);
-            const output = lines.join('\n');
-            return output;
+            const emaResult = await getEMA({
+                project: id,
+                interval,
+                from,
+                to,
+                period,
+            });
+            return formatIndicatorData(emaResult);
         }
-        catch (err) {
-            return formatToolError(err, 'calculating EMA');
+        catch (e) {
+            if (e instanceof InsufficientDataError) {
+                return `Insufficient data: got ${e.got} data points but need at least ${e.required} for EMA${period}.`;
+            }
+            return formatToolError(e, 'calculating EMA');
         }
     },
 });
@@ -238,66 +148,22 @@ export const getRSITool = tool({
             .describe('Data interval: "daily" or "hourly". Defaults to "daily".'),
     }),
     execute: async ({ id, period, from, to, interval }) => {
+        const effectivePeriod = period ?? 14;
         try {
-            const effectivePeriod = period ?? 14;
-            const minRequired = effectivePeriod + 1;
-            const client = getMarketClient();
-            const effectiveInterval = interval ?? 'daily';
-            const adjustedFrom = adjustFromDate(from, minRequired, effectiveInterval);
-            const ohlcData = await client.getOHLC(id, adjustedFrom, to, effectiveInterval);
-            if (ohlcData.length < minRequired) {
-                return `Insufficient data: got ${ohlcData.length} data points but need at least ${minRequired} for RSI-${effectivePeriod}.`;
-            }
-            const rsiData = computeRSI(ohlcData, effectivePeriod);
-            if (rsiData.length === 0) {
-                return `Could not compute RSI-${effectivePeriod} for ${id}.`;
-            }
-            // Filter results to original date range
-            const originalFromTime = new Date(from).getTime();
-            const filteredData = rsiData.filter((point) => point.timestamp >= originalFromTime);
-            if (filteredData.length === 0) {
-                return `No RSI-${effectivePeriod} data available within the requested date range for ${id}.`;
-            }
-            const lines = [
-                `RSI-${effectivePeriod} for ${id} (${effectiveInterval}, ${filteredData.length} values):`,
-                '',
-            ];
-            for (const point of filteredData) {
-                const date = new Date(point.timestamp).toISOString().split('T')[0];
-                const rsiValue = point.value.toFixed(2);
-                let status = '';
-                if (point.value >= 70) {
-                    status = ' [OVERBOUGHT]';
-                }
-                else if (point.value <= 30) {
-                    status = ' [OVERSOLD]';
-                }
-                lines.push(`${date}: ${rsiValue}${status}`);
-            }
-            const latestRSI = filteredData[filteredData.length - 1].value;
-            let interpretation = '';
-            if (latestRSI >= 70) {
-                interpretation =
-                    'The RSI is in overbought territory (>=70), which may indicate the asset is overvalued and could see a pullback.';
-            }
-            else if (latestRSI <= 30) {
-                interpretation =
-                    'The RSI is in oversold territory (<=30), which may indicate the asset is undervalued and could see a bounce.';
-            }
-            else if (latestRSI >= 50) {
-                interpretation = 'The RSI shows bullish momentum (above 50).';
-            }
-            else {
-                interpretation = 'The RSI shows bearish momentum (below 50).';
-            }
-            lines.push('');
-            lines.push(`Current RSI: ${latestRSI.toFixed(2)}`);
-            lines.push(interpretation);
-            const output = lines.join('\n');
-            return output;
+            const rsi = await getRSI({
+                project: id,
+                interval,
+                from,
+                to,
+                period: effectivePeriod,
+            });
+            return formatIndicatorData(rsi);
         }
-        catch (err) {
-            return formatToolError(err, 'calculating RSI');
+        catch (e) {
+            if (e instanceof InsufficientDataError) {
+                return `Insufficient data: got ${e.got} data points but need at least ${e.required} for RSI${effectivePeriod}.`;
+            }
+            return formatToolError(e, 'calculating RSI');
         }
     },
 });
@@ -333,65 +199,26 @@ export const getMACDTool = tool({
             .describe('Data interval: "daily" or "hourly". Defaults to "daily".'),
     }),
     execute: async ({ id, fastPeriod, slowPeriod, signalPeriod, from, to, interval }) => {
+        const fast = fastPeriod ?? 12;
+        const slow = slowPeriod ?? 26;
+        const signal = signalPeriod ?? 9;
         try {
-            const fast = fastPeriod ?? 12;
-            const slow = slowPeriod ?? 26;
-            const signal = signalPeriod ?? 9;
-            const minRequired = slow + signal;
-            const client = getMarketClient();
-            const effectiveInterval = interval ?? 'daily';
-            const adjustedFrom = adjustFromDate(from, minRequired, effectiveInterval);
-            const ohlcData = await client.getOHLC(id, adjustedFrom, to, effectiveInterval);
-            if (ohlcData.length < minRequired) {
-                return `Insufficient data: got ${ohlcData.length} data points but need at least ${minRequired} for MACD(${fast},${slow},${signal}).`;
-            }
-            const macdData = computeMACD(ohlcData, fast, slow, signal);
-            if (macdData.length === 0) {
-                return `Could not compute MACD(${fast},${slow},${signal}) for ${id}.`;
-            }
-            // Filter results to original date range
-            const originalFromTime = new Date(from).getTime();
-            const filteredData = macdData.filter((point) => point.timestamp >= originalFromTime);
-            if (filteredData.length === 0) {
-                return `No MACD(${fast},${slow},${signal}) data available within the requested date range for ${id}.`;
-            }
-            const lines = [
-                `MACD(${fast},${slow},${signal}) for ${id} (${effectiveInterval}, ${filteredData.length} values):`,
-                '',
-                'Date | MACD | Signal | Histogram',
-                '--- | --- | --- | ---',
-            ];
-            for (const point of filteredData) {
-                const date = new Date(point.timestamp).toISOString().split('T')[0];
-                const macdVal = point.macd.toFixed(4);
-                const signalVal = point.signal.toFixed(4);
-                const histVal = point.histogram.toFixed(4);
-                lines.push(`${date} | ${macdVal} | ${signalVal} | ${signPrefix(point.histogram)}${histVal}`);
-            }
-            const latest = filteredData[filteredData.length - 1];
-            const previous = filteredData.length > 1 ? filteredData[filteredData.length - 2] : null;
-            let crossover = '';
-            if (previous !== null) {
-                if (previous.macd <= previous.signal && latest.macd > latest.signal) {
-                    crossover = 'BULLISH CROSSOVER detected (MACD crossed above Signal line)!';
-                }
-                else if (previous.macd >= previous.signal && latest.macd < latest.signal) {
-                    crossover = 'BEARISH CROSSOVER detected (MACD crossed below Signal line)!';
-                }
-            }
-            const trend = latest.macd > latest.signal ? 'bullish (MACD above signal)' : 'bearish (MACD below signal)';
-            const momentum = latest.histogram > 0 ? 'positive' : 'negative';
-            lines.push('');
-            lines.push(`Current trend: ${trend}`);
-            lines.push(`Histogram momentum: ${momentum}`);
-            if (crossover) {
-                lines.push(crossover);
-            }
-            const output = lines.join('\n');
-            return output;
+            const macdResult = await getMACD({
+                project: id,
+                interval,
+                from,
+                to,
+                fast,
+                slow,
+                signal,
+            });
+            return formatMACDData(macdResult);
         }
-        catch (err) {
-            return formatToolError(err, 'calculating MACD');
+        catch (e) {
+            if (e instanceof InsufficientDataError) {
+                return `Insufficient data: got ${e.got} data points but need at least ${e.required} for MACD(${fast},${slow},${signal}).`;
+            }
+            return formatToolError(e, 'calculating MACD');
         }
     },
 });
@@ -407,79 +234,28 @@ export const getBollingerTool = tool({
             .max(100)
             .optional()
             .describe('SMA period for the middle band. Defaults to 20.'),
-        stdDev: z
-            .number()
-            .min(0.5)
-            .max(5)
-            .optional()
-            .describe('Standard deviation multiplier for bands. Defaults to 2.'),
         interval: z
             .enum(['daily', 'hourly'])
             .optional()
             .describe('Data interval: "daily" or "hourly". Defaults to "daily".'),
     }),
-    execute: async ({ id, period, stdDev, from, to, interval }) => {
+    execute: async ({ id, period, from, to, interval }) => {
+        const effectivePeriod = period ?? 20;
         try {
-            const effectivePeriod = period ?? 20;
-            const effectiveStdDev = stdDev ?? 2;
-            const client = getMarketClient();
-            const effectiveInterval = interval ?? 'daily';
-            const adjustedFrom = adjustFromDate(from, effectivePeriod, effectiveInterval);
-            const ohlcData = await client.getOHLC(id, adjustedFrom, to, effectiveInterval);
-            if (ohlcData.length < effectivePeriod) {
-                return `Insufficient data: got ${ohlcData.length} data points but need at least ${effectivePeriod} for Bollinger Bands(${effectivePeriod},${effectiveStdDev}).`;
-            }
-            const bbData = computeBollingerBands(ohlcData, effectivePeriod, effectiveStdDev);
-            if (bbData.length === 0) {
-                return `Could not compute Bollinger Bands(${effectivePeriod},${effectiveStdDev}) for ${id}.`;
-            }
-            // Filter results to original date range
-            const originalFromTime = new Date(from).getTime();
-            const filteredData = bbData.filter((point) => point.timestamp >= originalFromTime);
-            if (filteredData.length === 0) {
-                return `No Bollinger Bands(${effectivePeriod},${effectiveStdDev}) data available within the requested date range for ${id}.`;
-            }
-            const lines = [
-                `Bollinger Bands(${effectivePeriod},${effectiveStdDev}) for ${id} (${effectiveInterval}, ${filteredData.length} values):`,
-                '',
-                'Date | Upper | Middle | Lower',
-                '--- | --- | --- | ---',
-            ];
-            for (const point of filteredData) {
-                const date = new Date(point.timestamp).toISOString().split('T')[0];
-                lines.push(`${date} | $${point.upper.toFixed(2)} | $${point.middle.toFixed(2)} | $${point.lower.toFixed(2)}`);
-            }
-            const latest = filteredData[filteredData.length - 1];
-            const latestPrice = ohlcData[ohlcData.length - 1][4];
-            const bandwidth = ((latest.upper - latest.lower) / latest.middle) * 100;
-            let position = '';
-            const percentB = (latestPrice - latest.lower) / (latest.upper - latest.lower);
-            if (latestPrice > latest.upper) {
-                position = 'ABOVE upper band (potential overbought)';
-            }
-            else if (latestPrice < latest.lower) {
-                position = 'BELOW lower band (potential oversold)';
-            }
-            else if (percentB > 0.8) {
-                position = 'near upper band (approaching overbought)';
-            }
-            else if (percentB < 0.2) {
-                position = 'near lower band (approaching oversold)';
-            }
-            else {
-                position = 'within bands (neutral zone)';
-            }
-            lines.push('');
-            lines.push(`Current price: $${latestPrice.toFixed(2)}`);
-            lines.push(`Bands: Upper $${latest.upper.toFixed(2)} | Middle $${latest.middle.toFixed(2)} | Lower $${latest.lower.toFixed(2)}`);
-            lines.push(`Bandwidth: ${bandwidth.toFixed(2)}%`);
-            lines.push(`%B (position within bands): ${(percentB * 100).toFixed(1)}%`);
-            lines.push(`Price position: ${position}`);
-            const output = lines.join('\n');
-            return output;
+            const bbResult = await getBollingerBands({
+                project: id,
+                interval,
+                from,
+                to,
+                period: effectivePeriod,
+            });
+            return formatBollingerData(bbResult);
         }
-        catch (err) {
-            return formatToolError(err, 'calculating Bollinger Bands');
+        catch (e) {
+            if (e instanceof InsufficientDataError) {
+                return `Insufficient data: got ${e.got} data points but need at least ${e.required} for Bollinger Bands(${effectivePeriod}).`;
+            }
+            return formatToolError(e, 'calculating Bollinger Bands');
         }
     },
 });

package/dist/shared/agent/tools/market/utils.js

@@ -0,0 +1,71 @@
+import { truncateTimeseries, truncationLabel } from '../../utils.js';
+export function formatOhlcData(data) {
+    const truncated = truncateTimeseries(data, {
+        maxDisplay: 30,
+        headCount: 10,
+        tailCount: 10,
+    });
+    const lines = ['Date | Open | High | Low | Close'];
+    for (const point of truncated) {
+        if (point === null) {
+            lines.push(truncationLabel(data.length, 20));
+            continue;
+        }
+        const iso = new Date(point[0]).toISOString();
+        const date = iso.slice(0, 13) + ':00';
+        const open = point[1].toFixed(2);
+        const high = point[2].toFixed(2);
+        const low = point[3].toFixed(2);
+        const close = point[4].toFixed(2);
+        lines.push(`${date} | $${open} | $${high} | $${low} | $${close}`);
+    }
+    return lines.join('\n');
+}
+function formatDate(isoTimestamp) {
+    const iso = new Date(isoTimestamp).toISOString();
+    const date = iso.slice(0, 13) + ':00';
+    return date;
+}
+function formatNum(value) {
+    const formatted = `$${value.toFixed(2)}`;
+    return formatted;
+}
+export function formatIndicatorData(data) {
+    const truncated = truncateTimeseries(data);
+    const lines = ['Date | Value', '--- | ---'];
+    for (const point of truncated) {
+        if (point === null) {
+            lines.push(truncationLabel(data.length, 15));
+            continue;
+        }
+        lines.push(`${formatDate(point.timestamp)} | ${formatNum(point.value)}`);
+    }
+    const result = lines.join('\n');
+    return result;
+}
+export function formatMACDData(data) {
+    const truncated = truncateTimeseries(data);
+    const lines = ['Date | MACD | Signal | Histogram'];
+    for (const point of truncated) {
+        if (point === null) {
+            lines.push(truncationLabel(data.length, 15));
+            continue;
+        }
+        lines.push(`${formatDate(point.timestamp)} | ${formatNum(point.macd)} | ${formatNum(point.signal)} | ${formatNum(point.histogram)}`);
+    }
+    const result = lines.join('\n');
+    return result;
+}
+export function formatBollingerData(data) {
+    const truncated = truncateTimeseries(data);
+    const lines = ['Date | Upper | Middle | Lower'];
+    for (const point of truncated) {
+        if (point === null) {
+            lines.push(truncationLabel(data.length, 15));
+            continue;
+        }
+        lines.push(`${formatDate(point.timestamp)} | ${formatNum(point.upper)} | ${formatNum(point.middle)} | ${formatNum(point.lower)}`);
+    }
+    const result = lines.join('\n');
+    return result;
+}

package/dist/shared/agent/tools/mindshare/tools.js

@@ -1,7 +1,7 @@
 import { tool } from 'ai';
 import { z } from 'zod';
+import { formatPeriodChange, formatToolError, signPrefix, truncateTimeseries, truncationLabel, } from '../../utils.js';
 import { getMindshareClient, } from './client.js';
-import { formatToolError, signPrefix, truncateTimeseries, truncationLabel, formatPeriodChange, } from '../formatting.js';
 const timeframeSchema = z
     .enum(['30m', '24h', '3D', '7D', '1M', '3M', 'YTD'])
     .optional()

package/dist/shared/agent/tools/ta/index.js

@@ -1 +1,3 @@
-export { computeSMA, computeEMA, computeRSI, computeMACD, computeBollingerBands } from './indicators.js';
+export {};
+// Indicator implementations have been moved to shared/ta/service.ts
+// This module is intentionally empty.

package/dist/shared/agent/types.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/agent/utils.js

@@ -41,3 +41,47 @@ export function stripCodeFences(text) {
     }
     return trimmed;
 }
+/**
+ * Truncate a timeseries array for display, keeping head and tail with a `null` gap in between.
+ * Returns the original array unchanged if it fits within `maxDisplay`.
+ */
+export function truncateTimeseries(data, { maxDisplay = 20, headCount = 5, tailCount = 10, } = {}) {
+    if (data.length <= maxDisplay) {
+        return data;
+    }
+    const truncated = [...data.slice(0, headCount), null, ...data.slice(-tailCount)];
+    return truncated;
+}
+/**
+ * Label for the truncation gap (e.g. `"... (42 more points) ..."`).
+ */
+export function truncationLabel(totalLength, shownCount) {
+    const hidden = totalLength - shownCount;
+    const label = `... (${hidden} more) ...`;
+    return label;
+}
+/**
+ * Standardised error message for tool catch blocks.
+ */
+export function formatToolError(err, context) {
+    const message = extractErrorMessage(err);
+    const result = `Error ${context}: ${message}`;
+    return result;
+}
+/**
+ * Returns '+' for non-negative values, '' for negative (the minus sign is already present).
+ */
+export function signPrefix(value) {
+    const prefix = value >= 0 ? '+' : '';
+    return prefix;
+}
+/**
+ * Format a period-change percentage from first → last value.
+ * Returns e.g. `"Period change: +12.34%"`.
+ */
+export function formatPeriodChange(firstValue, lastValue) {
+    const changePercent = ((lastValue - firstValue) / firstValue) * 100;
+    const sign = signPrefix(changePercent);
+    const result = `Period change: ${sign}${changePercent.toFixed(2)}%`;
+    return result;
+}