@panoptic-eng/mcp 0.1.0 → 0.1.2

package/dist/{server--YF2LHqv.js → server-CabyB7Fb.js}

@@ -1,6 +1,6 @@
-import { DEFAULT_VEGOID, MAX_TICK, MIN_TICK, STANDARD_TICK_WIDTHS, WAD, createMemoryStorage, createTokenIdBuilder, decodeTokenId, getAccountBuyingPower, getAccountCollateral, getAccountGreeks, getAccountHistory, getAccountPremia, getChainDeployment, getDeltaHedgeParams, getLegDelta, getMarginBuffer, getNetLiquidationValues, getOpenPositionPreview, getPool, getPoolDeploymentBlock, getPoolLiquidities, getPositions, getTrackedPositionIds, hasLoanOrCredit, hasLongLeg, isCall, isCreditLeg, isLiquidatable, isLoanLeg, isShortOnly, isSpread, scanChunks, simulateClosePosition, syncPositions } from "@panoptic-eng/sdk/v2";
+import { DEFAULT_VEGOID, MAX_TICK, MIN_TICK, STANDARD_TICK_WIDTHS, WAD, createMemoryStorage, createTokenIdBuilder, decodeTokenId, getAccountBuyingPower, getAccountCollateral, getAccountGreeks, getAccountHistory, getAccountPremia, getChainDeployment, getDeltaHedgeParams, getLegDelta, getMarginBuffer, getNetLiquidationValues, getOpenPositionPreview, getPool, getPoolDeploymentBlock, getPoolLiquidities, getPositions, getTrackedPositionIds, hasLoanOrCredit, hasLongLeg, isCall, isCreditLeg, isLiquidatable, isLoanLeg, isShortOnly, isSpread, roundToTickSpacing, scanChunks, simulateClosePosition, syncPositions, tickToPriceDecimalScaled } from "@panoptic-eng/sdk/v2";
 import { createPublicClient, getAddress, http, isAddress, keccak256, toBytes, toHex } from "viem";
-import { base, mainnet, sepolia } from "viem/chains";
+import { mainnet, sepolia } from "viem/chains";
 import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
@@ -9,27 +9,29 @@ import { z } from "zod";
 /** viem chain definitions (carry the Multicall3 address the SDK reads rely on). */
 const VIEM_CHAINS = {
 	[mainnet.id]: mainnet,
-	[base.id]: base,
 	[sepolia.id]: sepolia
 };
-/** Chain ids Panoptic has deployments for (mainnet, Base, Sepolia). */
-const KNOWN_CHAIN_IDS = [
-	mainnet.id,
-	base.id,
-	sepolia.id
-];
+const KNOWN_CHAIN_IDS = [mainnet.id, sepolia.id];
 /**
-* Resolve an optional user-supplied chain-id string to a trusted known-chain
-* constant, falling back to `fallback` when omitted/blank. Matches on canonical
-* decimal form only (never Number(), so "1e0" is rejected) and throws on
-* unsupported ids.
+* Validate a user-supplied chain-id string against the trusted known-chain
+* constants AND the SDK deployment registry, returning the matched id. Matches
+* on canonical decimal form only (never Number(), so "1e0" is rejected). This is
+* the single validation path shared by resolveChainId (per-call args) and
+* resolveConfig (startup) so the two can't drift.
 */
-function resolveChainId(rawChainId, fallback) {
-	if (rawChainId === void 0 || rawChainId.trim() === "") return fallback;
+function toSupportedChainId(rawChainId) {
 	const chainId = KNOWN_CHAIN_IDS.find((id) => id.toString() === rawChainId.trim());
-	if (chainId === void 0) throw new Error(`Unsupported chain id ${rawChainId}. Supported: ${KNOWN_CHAIN_IDS.join(", ")}.`);
+	if (chainId === void 0 || getChainDeployment(chainId) === void 0) throw new Error(`Unsupported chain id ${rawChainId}. Supported: ${KNOWN_CHAIN_IDS.join(", ")}.`);
 	return chainId;
 }
+/**
+* Resolve an optional user-supplied chain-id string to a trusted, deployed
+* known-chain constant, falling back to `fallback` when omitted/blank.
+*/
+function resolveChainId(rawChainId, fallback) {
+	if (rawChainId === void 0 || rawChainId.trim() === "") return fallback;
+	return toSupportedChainId(rawChainId);
+}
 var ConfigError = class extends Error {};
 /**
 * Resolve server config from CLI flags (`--rpc-url`, `--chain-id`,
@@ -43,8 +45,12 @@ function resolveConfig(argv, env) {
 	if (!rpcUrl) throw new ConfigError("Missing RPC URL. Set PANOPTIC_RPC_URL or pass --rpc-url <url>.");
 	const rawChainId = flags["chain-id"] ?? env.PANOPTIC_CHAIN_ID;
 	if (!rawChainId) throw new ConfigError("Missing chain id. Set PANOPTIC_CHAIN_ID or pass --chain-id <id>.");
-	const chainId = KNOWN_CHAIN_IDS.find((id) => id.toString() === rawChainId.trim());
-	if (chainId === void 0 || getChainDeployment(chainId) === void 0) throw new ConfigError(`Unsupported chain id ${rawChainId}. Supported: ${KNOWN_CHAIN_IDS.join(", ")}.`);
+	let chainId;
+	try {
+		chainId = toSupportedChainId(rawChainId);
+	} catch (err) {
+		throw new ConfigError(err instanceof Error ? err.message : String(err));
+	}
 	const subgraphUrl = flags["subgraph-url"] ?? env.PANOPTIC_SUBGRAPH_URL ?? void 0;
 	return {
 		rpcUrl,
@@ -65,7 +71,8 @@ async function createContext(config) {
 	return {
 		config,
 		client,
-		deployment
+		deployment,
+		session: {}
 	};
 }
 function parseFlags(argv) {
@@ -94,6 +101,46 @@ function parseAccountAddress(address) {
 	return getAddress(address);
 }
 
+//#endregion
+//#region src/numeric.ts
+/**
+* Shared parsing for the decimal-/hex-string numeric inputs every tool accepts.
+* Centralizes the validation so malformed input fails early with a consistent,
+* readable message instead of a raw `BigInt()` "Cannot convert" throw (or, for
+* `Number()`, silent coercion of forms like "1e9").
+*/
+const UNSIGNED = /^\d+$/;
+const SIGNED = /^-?\d+$/;
+/**
+* Parse a required decimal integer string to a bigint. Set `signed` to allow a
+* leading `-` (e.g. ticks, target delta); otherwise only non-negative integers
+* are accepted (blocks, epochs, sizes).
+*/
+function parseDecimalBigInt(raw, label, opts = {}) {
+	const trimmed = raw.trim();
+	const pattern = opts.signed ? SIGNED : UNSIGNED;
+	if (!pattern.test(trimmed)) throw new Error(`${label} must be a ${opts.signed ? "decimal" : "non-negative decimal"} integer string.`);
+	return BigInt(trimmed);
+}
+/**
+* Like {@link parseDecimalBigInt} but treats `undefined` and blank/whitespace
+* strings as "not provided", returning `undefined`.
+*/
+function parseOptionalDecimalBigInt(raw, label, opts = {}) {
+	if (raw === void 0 || raw.trim() === "") return void 0;
+	return parseDecimalBigInt(raw, label, opts);
+}
+/**
+* Parse a TokenId supplied as either a 0x-hex or a decimal string. TokenIds are
+* unsigned, so both forms map straight through `BigInt`, with a readable error
+* on anything else.
+*/
+function parseTokenId(raw, label = "tokenId") {
+	const trimmed = raw.trim();
+	if (!/^(0x[0-9a-fA-F]+|\d+)$/.test(trimmed)) throw new Error(`${label} must be a 0x-hex or decimal string.`);
+	return BigInt(trimmed);
+}
+
 //#endregion
 //#region src/serialize.ts
 /**
@@ -166,42 +213,82 @@ function buildEnvelope(input) {
 //#region src/tools/positions.ts
 const STABLE_SYMBOL = /^(usdc|usdt|usdbc|usds|usde|dai|frax|lusd|gusd|tusd|pyusd)$/i;
 /**
-* Resolve which token is the directional "asset" (non-numeraire). An explicit
-* override wins; otherwise the stablecoin side is treated as the numeraire and
-* the other token as the asset (defaulting to token0 if neither looks stable).
+* Choose the frame in which to report an account's aggregate net delta. An
+* explicit caller override always wins. Absent that, the stablecoin side (if
+* any) is treated as the numeraire so the other token becomes the reporting
+* frame — a convenience default only, surfaced with `source`/`reason` so callers
+* can see it was guessed and re-request a different frame.
 */
-function inferAssetIndex(pool, override) {
+function suggestDeltaFrame(pool, override) {
 	if (override !== void 0) return {
-		asset: override === 0 ? 0n : 1n,
-		inferred: false
+		frame: override === 0 ? 0n : 1n,
+		source: "override",
+		reason: "Caller-specified reporting frame."
 	};
-	if (STABLE_SYMBOL.test(pool.collateralTracker0.symbol)) return {
-		asset: 1n,
-		inferred: true
+	const sym0 = pool.collateralTracker0.symbol;
+	const sym1 = pool.collateralTracker1.symbol;
+	if (STABLE_SYMBOL.test(sym0)) return {
+		frame: 1n,
+		source: "heuristic",
+		reason: `token0 (${sym0}) looks like a stablecoin numeraire, so net delta is reported in token1 (${sym1}) units.`
 	};
-	if (STABLE_SYMBOL.test(pool.collateralTracker1.symbol)) return {
-		asset: 0n,
-		inferred: true
+	if (STABLE_SYMBOL.test(sym1)) return {
+		frame: 0n,
+		source: "heuristic",
+		reason: `token1 (${sym1}) looks like a stablecoin numeraire, so net delta is reported in token0 (${sym0}) units.`
 	};
 	return {
-		asset: 0n,
-		inferred: true
+		frame: 0n,
+		source: "default",
+		reason: `Neither token (${sym0}/${sym1}) looks like a stablecoin; defaulting the reporting frame to token0. Pass assetIndex to choose the frame explicitly.`
+	};
+}
+/**
+* Resolve the delta reporting frame with precedence: explicit tool argument →
+* session preference (set via configure_session) → heuristic guess. Only the
+* last case sets `needsUserChoice`, signalling the caller to ask the user which
+* token they want their net delta denominated in.
+*/
+function resolveDeltaFrame(pool, argIndex, sessionPreference) {
+	if (argIndex !== void 0) return {
+		...suggestDeltaFrame(pool, argIndex),
+		source: "override",
+		needsUserChoice: false
+	};
+	if (sessionPreference !== void 0) {
+		const symbol = sessionPreference === 0n ? pool.collateralTracker0.symbol : pool.collateralTracker1.symbol;
+		return {
+			frame: sessionPreference,
+			source: "session",
+			reason: `Using the session's preferred reporting frame (${symbol}); set via configure_session.`,
+			needsUserChoice: false
+		};
+	}
+	return {
+		...suggestDeltaFrame(pool),
+		needsUserChoice: true
 	};
 }
+/** Explanatory note attached to every account-level net-delta figure. */
+const DELTA_FRAME_NOTE = "Net delta is a single figure expressed in the chosen reporting frame (assetIndex). It is not a claim about a canonical pool asset: each position leg carries its own asset, and selecting a frame overrides every leg into that frame. The sign and magnitude depend on the frame — pass assetIndex to report in the other token.";
 /**
 * Discover an account's open position ids on the configured pool via the SDK's
 * event-scan sync into a fresh in-memory store — no subgraph required. Returns
 * the populated storage so greeks reads (which read synced positions from
 * storage) can reuse it.
 */
+const SYNC_TTL_MS = 15e3;
+const SYNC_CACHE_MAX = 64;
 const syncCache = new Map();
 async function syncAccountPositions(ctx, account, fromBlock) {
 	const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
 	const chainId = BigInt(ctx.config.chainId);
 	const cacheKey = `${chainId}:${poolAddress}:${account}:${fromBlock ?? "default"}`;
+	const now = Date.now();
 	const cached = syncCache.get(cacheKey);
-	if (cached) return cached;
-	const pending = (async () => {
+	if (cached && cached.expiresAt > now) return cached.promise;
+	if (cached) syncCache.delete(cacheKey);
+	const promise = (async () => {
 		const storage = createMemoryStorage();
 		await syncPositions({
 			client: ctx.client,
@@ -224,9 +311,19 @@ async function syncAccountPositions(ctx, account, fromBlock) {
 			storage
 		};
 	})();
-	syncCache.set(cacheKey, pending);
-	pending.catch(() => syncCache.delete(cacheKey));
-	return pending;
+	if (syncCache.size >= SYNC_CACHE_MAX) {
+		const oldest = syncCache.keys().next().value;
+		if (oldest !== void 0) syncCache.delete(oldest);
+	}
+	const entry = {
+		promise,
+		expiresAt: now + SYNC_TTL_MS
+	};
+	syncCache.set(cacheKey, entry);
+	promise.catch(() => {
+		if (syncCache.get(cacheKey) === entry) syncCache.delete(cacheKey);
+	});
+	return promise;
 }
 
 //#endregion
@@ -242,7 +339,7 @@ function registerAccountHealth(server, ctx) {
 	}, async ({ address, fromBlock }) => {
 		const account = parseAccountAddress(address);
 		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
-		const { poolAddress, tokenIds } = await syncAccountPositions(ctx, account, fromBlock ? BigInt(fromBlock) : void 0);
+		const { poolAddress, tokenIds } = await syncAccountPositions(ctx, account, parseOptionalDecimalBigInt(fromBlock, "fromBlock"));
 		const [buyingPower, marginBuffer, liquidation] = await Promise.all([
 			getAccountBuyingPower({
 				client: ctx.client,
@@ -270,11 +367,50 @@ function registerAccountHealth(server, ctx) {
 			openTokenIds: tokenIds,
 			buyingPower,
 			marginBuffer,
-			liquidation
+			liquidation,
+			...tokenIds.length === 0 ? { note: "No open positions found on this pool for this account; margin buffer/liquidation reflect an unlevered account. If positions are expected, widen the scan with fromBlock — public RPCs can truncate large eth_getLogs ranges." } : {}
 		});
 	});
 }
 
+//#endregion
+//#region src/tools/pool.ts
+const POOL_TTL_MS = 6e3;
+const POOL_CACHE_MAX = 8;
+const poolCache = new Map();
+/**
+* Read the configured pool's live state, reusing a recent read when one is in
+* flight or fresh. Failures are not cached, so the next call retries.
+*/
+async function getCachedPool(ctx) {
+	const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
+	const chainId = BigInt(ctx.config.chainId);
+	const cacheKey = `${chainId}:${poolAddress}`;
+	const now = Date.now();
+	const cached = poolCache.get(cacheKey);
+	if (cached && cached.expiresAt > now) return cached.promise;
+	if (cached) poolCache.delete(cacheKey);
+	const promise = getPool({
+		client: ctx.client,
+		poolAddress,
+		chainId,
+		stateViewAddress: ctx.deployment.infrastructure.stateView
+	});
+	if (poolCache.size >= POOL_CACHE_MAX) {
+		const oldest = poolCache.keys().next().value;
+		if (oldest !== void 0) poolCache.delete(oldest);
+	}
+	const entry = {
+		promise,
+		expiresAt: now + POOL_TTL_MS
+	};
+	poolCache.set(cacheKey, entry);
+	promise.catch(() => {
+		if (poolCache.get(cacheKey) === entry) poolCache.delete(cacheKey);
+	});
+	return promise;
+}
+
 //#endregion
 //#region src/tools/advisePosition.ts
 const NEAR_LIQUIDATION_TICKS = 500n;
@@ -319,26 +455,14 @@ function registerAdvisePosition(server, ctx) {
 			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan.")
 		}
 	}, async ({ tokenId, address, fromBlock }) => {
-		if (!isAddress(address)) throw new Error(`Invalid address: ${address}`);
-		const account = getAddress(address);
-		let id;
-		try {
-			id = BigInt(tokenId.trim());
-		} catch {
-			throw new Error(`Invalid tokenId (expected a 0x-hex or decimal string): ${tokenId}`);
-		}
+		const account = parseAccountAddress(address);
+		const id = parseTokenId(tokenId);
 		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
 		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
-		const chainId = BigInt(ctx.config.chainId);
-		const pool = await getPool({
-			client: ctx.client,
-			poolAddress,
-			chainId,
-			stateViewAddress: ctx.deployment.infrastructure.stateView
-		});
+		const pool = await getCachedPool(ctx);
 		const decoded = decodeTokenId(id);
 		const legs = decoded.legs.map((leg) => analyzeLeg(leg, pool.currentTick));
-		const { tokenIds } = await syncAccountPositions(ctx, account, fromBlock ? BigInt(fromBlock) : void 0);
+		const { tokenIds } = await syncAccountPositions(ctx, account, parseOptionalDecimalBigInt(fromBlock, "fromBlock"));
 		const owned = tokenIds.some((t) => t === id);
 		const idList = owned ? tokenIds : [...tokenIds, id];
 		const [{ positions }, premia, marginBuffer, liquidation] = await Promise.all([
@@ -435,6 +559,35 @@ function registerAdvisePosition(server, ctx) {
 	});
 }
 
+//#endregion
+//#region src/tools/tickMath.ts
+/**
+* Clamp a tick into the valid Uniswap range [MIN_TICK, MAX_TICK]. The SDK
+* provides tick↔price math and roundToTickSpacing but no plain clamp, so this
+* one small helper lives here and is shared by the tools that build tick bands.
+*/
+function clampTick(tick) {
+	if (tick < MIN_TICK) return MIN_TICK;
+	if (tick > MAX_TICK) return MAX_TICK;
+	return tick;
+}
+/**
+* Round a tick to the nearest `spacing` multiple, guaranteed to stay within the
+* valid range. roundToTickSpacing rounds to the *nearest* multiple, so a value
+* at the range edge can round outward past MIN_TICK/MAX_TICK when spacing does
+* not divide them; this clamps the result to the inward-aligned multiples
+* (largest ≤ MAX_TICK, smallest ≥ MIN_TICK) so the output is always both a
+* `spacing` multiple AND in range — required by callers like scanChunks.
+*/
+function roundToSpacingInRange(tick, spacing) {
+	const rounded = roundToTickSpacing(clampTick(tick), spacing);
+	const maxAligned = MAX_TICK - MAX_TICK % spacing;
+	const minAligned = MIN_TICK - MIN_TICK % spacing;
+	if (rounded > maxAligned) return maxAligned;
+	if (rounded < minAligned) return minAligned;
+	return rounded;
+}
+
 //#endregion
 //#region src/tools/chunkSpread.ts
 const DEFAULT_TIMESCALE = "1D";
@@ -443,15 +596,6 @@ const DEFAULT_SCAN_HALFSPAN = 6000n;
 function toMultiplier(spreadWad) {
 	return Number(spreadWad * 10000n / WAD) / 1e4;
 }
-function clampTick$1(tick) {
-	if (tick < MIN_TICK) return MIN_TICK;
-	if (tick > MAX_TICK) return MAX_TICK;
-	return tick;
-}
-/** Floor a tick to the nearest lower multiple of `step`. */
-function alignDown(tick, step) {
-	return tick - (tick % step + step) % step;
-}
 function registerChunkSpread(server, ctx) {
 	server.registerTool("chunk_spread", {
 		title: "Chunk spread multipliers",
@@ -472,21 +616,16 @@ function registerChunkSpread(server, ctx) {
 	}, async ({ timescale, width, tickLower, tickUpper, vegoid }) => {
 		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
 		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
-		const pool = await getPool({
-			client: ctx.client,
-			poolAddress,
-			chainId: BigInt(ctx.config.chainId),
-			stateViewAddress: ctx.deployment.infrastructure.stateView
-		});
+		const pool = await getCachedPool(ctx);
 		const resolvedTimescale = timescale ?? DEFAULT_TIMESCALE;
 		const rawWidth = width !== void 0 ? BigInt(width) : STANDARD_TICK_WIDTHS[resolvedTimescale];
 		const chunkWidth = rawWidth < pool.tickSpacing ? pool.tickSpacing : rawWidth - rawWidth % pool.tickSpacing;
 		const vg = vegoid !== void 0 ? BigInt(vegoid) : DEFAULT_VEGOID;
 		const halfWidthsRaw = DEFAULT_SCAN_HALFSPAN / chunkWidth;
 		const halfWidths = halfWidthsRaw < 2n ? 2n : halfWidthsRaw;
-		const center = alignDown(pool.currentTick, chunkWidth);
-		const lower = tickLower !== void 0 ? alignDown(clampTick$1(BigInt(tickLower)), chunkWidth) : alignDown(clampTick$1(center - halfWidths * chunkWidth), chunkWidth);
-		const upper = tickUpper !== void 0 ? alignDown(clampTick$1(BigInt(tickUpper)), chunkWidth) : alignDown(clampTick$1(center + halfWidths * chunkWidth), chunkWidth);
+		const center = roundToSpacingInRange(pool.currentTick, chunkWidth);
+		const lower = tickLower !== void 0 ? roundToSpacingInRange(parseDecimalBigInt(tickLower, "tickLower", { signed: true }), chunkWidth) : roundToSpacingInRange(center - halfWidths * chunkWidth, chunkWidth);
+		const upper = tickUpper !== void 0 ? roundToSpacingInRange(parseDecimalBigInt(tickUpper, "tickUpper", { signed: true }), chunkWidth) : roundToSpacingInRange(center + halfWidths * chunkWidth, chunkWidth);
 		const { chunks, _meta } = await scanChunks({
 			client: ctx.client,
 			poolAddress,
@@ -587,7 +726,7 @@ function registerGetPortfolio(server, ctx) {
 		}
 	}, async ({ address, fromBlock }) => {
 		const account = parseAccountAddress(address);
-		const { poolAddress, chainId, tokenIds, storage } = await syncAccountPositions(ctx, account, fromBlock ? BigInt(fromBlock) : void 0);
+		const { poolAddress, chainId, tokenIds, storage } = await syncAccountPositions(ctx, account, parseOptionalDecimalBigInt(fromBlock, "fromBlock"));
 		const [positions, collateral, greeks] = await Promise.all([
 			getPositions({
 				client: ctx.client,
@@ -614,7 +753,55 @@ function registerGetPortfolio(server, ctx) {
 			openTokenIds: tokenIds,
 			positions,
 			collateral,
-			greeks
+			greeks,
+			...tokenIds.length === 0 ? { note: "No open positions found on this pool for this account (positions/greeks reflect collateral only). If positions are expected, widen the scan with fromBlock — public RPCs can truncate large eth_getLogs ranges." } : {}
+		});
+	});
+}
+
+//#endregion
+//#region src/tools/session.ts
+/**
+* Build the response a delta tool returns when it cannot pick a reporting frame
+* on its own. Rather than silently guessing which token the user wants their net
+* delta denominated in, the tool surfaces a question the agent should put to the
+* user, plus the exact follow-up call to make. `suggestion` carries the
+* heuristic guess so the agent can offer a sensible default.
+*/
+function assetPreferenceRequired(params) {
+	const { token0, token1, suggestedAssetIndex, suggestionReason } = params;
+	const suggestedSymbol = suggestedAssetIndex === 0n ? token0 : token1;
+	return jsonResult({
+		status: "needs_asset_preference",
+		question: `Which token should net delta be reported in for this pool — ${token0} (assetIndex 0) or ${token1} (assetIndex 1)? There is no canonical answer: it is a denomination choice (e.g. some traders treat ETH as the numeraire, others USDC).`,
+		suggestion: {
+			assetIndex: suggestedAssetIndex,
+			symbol: suggestedSymbol,
+			reason: suggestionReason
+		},
+		howToProceed: "Ask the user which token they prefer, then either pass `assetIndex` (0 or 1) directly to this tool for a one-off, or call `configure_session` with `assetIndex` to set it for the rest of the session so you are not asked again.",
+		tokens: {
+			token0,
+			token1
+		}
+	});
+}
+function registerConfigureSession(server, ctx) {
+	server.registerTool("configure_session", {
+		title: "Configure the session",
+		description: "Set (or read) preferences for this MCP session. Currently records the user's preferred delta reporting frame (`assetIndex`) so delta tools (suggest_delta_hedge, hedge_params) report net delta in the chosen token's units without asking again. There is no canonical pool asset — this is a per-user denomination choice, so ask the user before setting it. Call with no arguments to read the current session preferences.",
+		inputSchema: {
+			assetIndex: z.union([z.literal(0), z.literal(1)]).optional().describe("Preferred delta reporting frame for the session: 0 = report net delta in token0 units, 1 = token1 units. Omit to leave unchanged."),
+			clearAssetIndex: z.boolean().optional().describe("Set true to clear a previously set preferred assetIndex.")
+		}
+	}, async ({ assetIndex, clearAssetIndex }) => {
+		if (clearAssetIndex === true) ctx.session.preferredAssetIndex = void 0;
+		else if (assetIndex !== void 0) ctx.session.preferredAssetIndex = assetIndex === 0 ? 0n : 1n;
+		const current = ctx.session.preferredAssetIndex;
+		return jsonResult({
+			chainId: ctx.config.chainId,
+			preferences: { preferredAssetIndex: current },
+			note: current === void 0 ? "No preferred delta reporting frame is set. Delta tools will ask the user (or you can pass assetIndex per call)." : `Net delta will be reported in token${current} units for this session unless a call overrides it with an explicit assetIndex.`
 		});
 	});
 }
@@ -630,32 +817,17 @@ function registerHedgeParams(server, ctx) {
 			tokenId: z.string().optional().describe("TokenId (0x-hex or decimal) for single-position hedging. Requires positionSize."),
 			positionSize: z.string().optional().describe("Position size (decimal string). Required with tokenId."),
 			targetDelta: z.string().optional().describe("Target delta in asset smallest units. Defaults to 0 (delta-neutral)."),
-			assetIndex: z.union([z.literal(0), z.literal(1)]).optional().describe("Directional asset (0/1) for whole-portfolio mode. Defaults to inferring the non-stablecoin token."),
+			assetIndex: z.union([z.literal(0), z.literal(1)]).optional().describe("Reporting frame for whole-portfolio net delta: 0 = token0 units, 1 = token1 units. A denomination choice that overrides each leg's own asset when aggregating, NOT a canonical pool asset. Ignored in single-position (tokenId) mode, where the leg's own asset is used. If omitted and no session preference is set (via configure_session), the tool asks the user which token to use instead of guessing."),
 			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan.")
 		}
 	}, async ({ address, tokenId, positionSize, targetDelta, assetIndex, fromBlock }) => {
 		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
 		const chainId = BigInt(ctx.config.chainId);
-		let target;
-		try {
-			target = targetDelta !== void 0 ? BigInt(targetDelta) : 0n;
-		} catch {
-			throw new Error(`Invalid targetDelta (expected a decimal string): ${targetDelta}`);
-		}
+		const target = targetDelta !== void 0 ? parseDecimalBigInt(targetDelta, "targetDelta", { signed: true }) : 0n;
 		if (tokenId !== void 0) {
 			if (positionSize === void 0) throw new Error("positionSize is required when hedging a single tokenId.");
-			let id;
-			let size;
-			try {
-				id = BigInt(tokenId.trim());
-			} catch {
-				throw new Error(`Invalid tokenId (expected a 0x-hex or decimal string): ${tokenId}`);
-			}
-			try {
-				size = BigInt(positionSize);
-			} catch {
-				throw new Error(`Invalid positionSize (expected a decimal string): ${positionSize}`);
-			}
+			const id = parseTokenId(tokenId);
+			const size = parseDecimalBigInt(positionSize, "positionSize");
 			const hedge$1 = await getDeltaHedgeParams({
 				client: ctx.client,
 				poolAddress,
@@ -673,21 +845,17 @@ function registerHedgeParams(server, ctx) {
 			});
 		}
 		if (address === void 0) throw new Error("Provide either `address` (whole-portfolio) or `tokenId` + `positionSize` (single).");
-		if (!isAddress(address)) throw new Error(`Invalid address: ${address}`);
-		const account = getAddress(address);
-		const pool = await getPool({
-			client: ctx.client,
-			poolAddress,
-			chainId,
-			stateViewAddress: ctx.deployment.infrastructure.stateView
+		const account = parseAccountAddress(address);
+		const pool = await getCachedPool(ctx);
+		const frameResolution = resolveDeltaFrame(pool, assetIndex, ctx.session.preferredAssetIndex);
+		if (frameResolution.needsUserChoice) return assetPreferenceRequired({
+			token0: pool.collateralTracker0.symbol,
+			token1: pool.collateralTracker1.symbol,
+			suggestedAssetIndex: frameResolution.frame,
+			suggestionReason: frameResolution.reason
 		});
-		const { asset, inferred: assetInferred } = inferAssetIndex(pool, assetIndex);
-		let scanFromBlock;
-		try {
-			scanFromBlock = fromBlock ? BigInt(fromBlock) : void 0;
-		} catch {
-			throw new Error(`Invalid fromBlock (expected a decimal string): ${fromBlock}`);
-		}
+		const { frame: asset, source: assetFrameSource, reason: assetFrameReason } = frameResolution;
+		const scanFromBlock = parseOptionalDecimalBigInt(fromBlock, "fromBlock");
 		const { tokenIds, storage } = await syncAccountPositions(ctx, account, scanFromBlock);
 		const greeks = await getAccountGreeks({
 			client: ctx.client,
@@ -712,7 +880,13 @@ function registerHedgeParams(server, ctx) {
 			pool: poolAddress,
 			assetIndex: asset,
 			assetSymbol: asset === 0n ? pool.collateralTracker0.symbol : pool.collateralTracker1.symbol,
-			assetInferred,
+			deltaFrame: {
+				assetIndex: asset,
+				symbol: asset === 0n ? pool.collateralTracker0.symbol : pool.collateralTracker1.symbol,
+				source: assetFrameSource,
+				reason: assetFrameReason
+			},
+			deltaFrameNote: DELTA_FRAME_NOTE,
 			openTokenIds: tokenIds,
 			currentDelta: greeks.totalDelta,
 			targetDelta: target,
@@ -721,6 +895,486 @@ function registerHedgeParams(server, ctx) {
 	});
 }
 
+//#endregion
+//#region src/tools/vaults.ts
+const HYPO_VAULT_READ_ABI = [
+	{
+		type: "function",
+		name: "accountant",
+		inputs: [],
+		outputs: [{ type: "address" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "balanceOf",
+		inputs: [{ type: "address" }],
+		outputs: [{ type: "uint256" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "decimals",
+		inputs: [],
+		outputs: [{ type: "uint8" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "depositEpoch",
+		inputs: [],
+		outputs: [{ type: "uint128" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "depositEpochState",
+		inputs: [{ type: "uint256" }],
+		outputs: [
+			{ type: "uint128" },
+			{ type: "uint128" },
+			{ type: "uint128" }
+		],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "feeWallet",
+		inputs: [],
+		outputs: [{ type: "address" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "manager",
+		inputs: [],
+		outputs: [{ type: "address" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "name",
+		inputs: [],
+		outputs: [{ type: "string" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "performanceFeeBps",
+		inputs: [],
+		outputs: [{ type: "uint256" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "queuedDeposit",
+		inputs: [{ type: "address" }, { type: "uint256" }],
+		outputs: [{ type: "uint128" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "queuedWithdrawal",
+		inputs: [{ type: "address" }, { type: "uint256" }],
+		outputs: [
+			{ type: "uint128" },
+			{ type: "uint128" },
+			{ type: "bool" }
+		],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "reservedWithdrawalAssets",
+		inputs: [],
+		outputs: [{ type: "uint256" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "symbol",
+		inputs: [],
+		outputs: [{ type: "string" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "totalSupply",
+		inputs: [],
+		outputs: [{ type: "uint256" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "underlyingToken",
+		inputs: [],
+		outputs: [{ type: "address" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "userBasis",
+		inputs: [{ type: "address" }],
+		outputs: [{ type: "uint256" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "withdrawalEpoch",
+		inputs: [],
+		outputs: [{ type: "uint128" }],
+		stateMutability: "view"
+	},
+	{
+		type: "function",
+		name: "withdrawalEpochState",
+		inputs: [{ type: "uint256" }],
+		outputs: [
+			{ type: "uint128" },
+			{ type: "uint128" },
+			{ type: "uint128" }
+		],
+		stateMutability: "view"
+	}
+];
+const VAULTS = [{
+	key: "wethPlpVault",
+	managerKey: "wethPlpVaultManager",
+	underlyingKey: "weth",
+	label: "WETH PLP Vault",
+	strategy: "Passive liquidity provider"
+}, {
+	key: "usdcPlpVault",
+	managerKey: "usdcPlpVaultManager",
+	underlyingKey: "usdc",
+	label: "USDC PLP Vault",
+	strategy: "Passive liquidity provider"
+}];
+const UNDERLYINGS = {
+	1: {
+		weth: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+		usdc: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
+	},
+	11155111: {
+		weth: "0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14",
+		usdc: "0xFFFeD8254566B7F800f6D8CDb843ec75AE49B07A"
+	}
+};
+function readAddress(value) {
+	return typeof value === "string" && isAddress(value) ? getAddress(value) : void 0;
+}
+function getVaultRegistry(chainId) {
+	const dep = getChainDeployment(chainId);
+	if (dep === void 0) return [];
+	return getVaultRegistryFromDeployment(chainId, dep);
+}
+function getVaultRegistryFromDeployment(chainId, dep) {
+	const underlyings = UNDERLYINGS[chainId];
+	if (underlyings === void 0) return [];
+	return VAULTS.flatMap((vault) => {
+		const vaultAddress = readAddress(dep.hypovault.vaults[vault.key]);
+		const managerAddress = readAddress(dep.hypovault.managers[vault.managerKey]);
+		const accountantAddress = readAddress(dep.hypovault.core.accountant);
+		const underlyingToken = readAddress(underlyings[vault.underlyingKey]);
+		const panopticPool = readAddress(dep.panoptic.pool.panopticPool);
+		const collateralTracker0 = readAddress(dep.panoptic.pool.collateralTracker0);
+		const collateralTracker1 = readAddress(dep.panoptic.pool.collateralTracker1);
+		if (vaultAddress === void 0 || managerAddress === void 0 || accountantAddress === void 0 || underlyingToken === void 0 || panopticPool === void 0 || collateralTracker0 === void 0 || collateralTracker1 === void 0) return [];
+		return [{
+			chainId,
+			key: vault.key,
+			label: vault.label,
+			strategy: vault.strategy,
+			vaultAddress,
+			managerAddress,
+			accountantAddress,
+			underlyingToken,
+			panopticPool,
+			collateralTracker0,
+			collateralTracker1
+		}];
+	});
+}
+function findVaultByAddress(address, chainId) {
+	return getVaultRegistry(chainId).find((vault) => vault.vaultAddress === address);
+}
+function getVaultAddressRoles(address, chainId) {
+	const roles = [];
+	const registry = getVaultRegistry(chainId);
+	for (const vault of registry) {
+		if (vault.vaultAddress === address) roles.push(`hypovault:${vault.key}`);
+		if (vault.managerAddress === address) roles.push(`hypovault:${vault.key}:manager`);
+		if (vault.accountantAddress === address) roles.push(`hypovault:${vault.key}:accountant`);
+		if (vault.underlyingToken === address) roles.push(`hypovault:${vault.key}:underlyingToken`);
+	}
+	const dep = getChainDeployment(chainId);
+	if (dep !== void 0) {
+		const core = dep.hypovault.core;
+		const coreRoles = {
+			hypovaultFactory: core.factory,
+			hypovaultImplementation: core.hypoVaultImplementation,
+			hypovaultAccountant: core.accountant,
+			hypovaultRolesAuthority: core.rolesAuthority,
+			hypovaultCollateralTrackerDecoderAndSanitizer: core.collateralTrackerDecoderAndSanitizer
+		};
+		for (const [role, value] of Object.entries(coreRoles)) {
+			const candidate = readAddress(value);
+			if (candidate === address && !roles.includes(role)) roles.push(role);
+		}
+	}
+	return roles;
+}
+/**
+* Batch several HypoVault view reads into a single Multicall3 round-trip (all
+* resolved at one block, so the returned fields are mutually consistent). Uses
+* allowFailure:false so any reverting read throws, matching the previous
+* per-call behavior. Returns results positionally in the order of `calls`.
+*/
+async function multicallVault(ctx, vaultAddress, calls) {
+	const multicall = ctx.client.multicall;
+	return multicall({
+		contracts: calls.map((call) => ({
+			address: vaultAddress,
+			abi: HYPO_VAULT_READ_ABI,
+			functionName: call.functionName,
+			args: call.args ?? []
+		})),
+		allowFailure: false
+	});
+}
+function depositEpochStateTuple([assetsDeposited, sharesReceived, assetsFulfilled]) {
+	return {
+		assetsDeposited,
+		sharesReceived,
+		assetsFulfilled
+	};
+}
+function withdrawalEpochStateTuple([sharesWithdrawn, assetsReceived, sharesFulfilled]) {
+	return {
+		sharesWithdrawn,
+		assetsReceived,
+		sharesFulfilled
+	};
+}
+function queuedWithdrawalTuple([amount, basis, shouldRedeposit]) {
+	return {
+		amount,
+		basis,
+		shouldRedeposit
+	};
+}
+async function fetchVaultSummary(ctx, vaultAddress) {
+	const registry = findVaultByAddress(vaultAddress, ctx.config.chainId);
+	const [name, symbol, decimals, totalSupply, underlyingToken, manager, accountant, feeWallet, performanceFeeBps, depositEpoch, withdrawalEpoch, reservedWithdrawalAssets] = await multicallVault(ctx, vaultAddress, [
+		{ functionName: "name" },
+		{ functionName: "symbol" },
+		{ functionName: "decimals" },
+		{ functionName: "totalSupply" },
+		{ functionName: "underlyingToken" },
+		{ functionName: "manager" },
+		{ functionName: "accountant" },
+		{ functionName: "feeWallet" },
+		{ functionName: "performanceFeeBps" },
+		{ functionName: "depositEpoch" },
+		{ functionName: "withdrawalEpoch" },
+		{ functionName: "reservedWithdrawalAssets" }
+	]);
+	const [depositEpochState, withdrawalEpochState] = await multicallVault(ctx, vaultAddress, [{
+		functionName: "depositEpochState",
+		args: [depositEpoch]
+	}, {
+		functionName: "withdrawalEpochState",
+		args: [withdrawalEpoch]
+	}]);
+	return {
+		chainId: ctx.config.chainId,
+		vaultAddress,
+		registry,
+		metadata: {
+			name,
+			symbol,
+			decimals
+		},
+		totalSupply,
+		underlyingToken,
+		manager,
+		accountant,
+		feeWallet,
+		performanceFeeBps,
+		depositEpoch,
+		withdrawalEpoch,
+		reservedWithdrawalAssets,
+		currentDepositEpochState: depositEpochStateTuple(depositEpochState),
+		currentWithdrawalEpochState: withdrawalEpochStateTuple(withdrawalEpochState),
+		navAndSharePrice: "Not returned by this v1 tool: HypoVault totalAssets/convertToAssets require managerInput-aware accounting."
+	};
+}
+async function fetchVaultAccount(ctx, vaultAddress, account, requestedDepositEpoch, requestedWithdrawalEpoch) {
+	const [currentDepositEpoch, currentWithdrawalEpoch, shareBalance, userBasis] = await multicallVault(ctx, vaultAddress, [
+		{ functionName: "depositEpoch" },
+		{ functionName: "withdrawalEpoch" },
+		{
+			functionName: "balanceOf",
+			args: [account]
+		},
+		{
+			functionName: "userBasis",
+			args: [account]
+		}
+	]);
+	const depositEpoch = requestedDepositEpoch ?? currentDepositEpoch;
+	const withdrawalEpoch = requestedWithdrawalEpoch ?? currentWithdrawalEpoch;
+	const [queuedDeposit, queuedWithdrawal, depositEpochState, withdrawalEpochState] = await multicallVault(ctx, vaultAddress, [
+		{
+			functionName: "queuedDeposit",
+			args: [account, depositEpoch]
+		},
+		{
+			functionName: "queuedWithdrawal",
+			args: [account, withdrawalEpoch]
+		},
+		{
+			functionName: "depositEpochState",
+			args: [depositEpoch]
+		},
+		{
+			functionName: "withdrawalEpochState",
+			args: [withdrawalEpoch]
+		}
+	]);
+	const withdrawal = queuedWithdrawalTuple(queuedWithdrawal);
+	const depositEpochStateResult = depositEpochStateTuple(depositEpochState);
+	const withdrawalEpochStateResult = withdrawalEpochStateTuple(withdrawalEpochState);
+	return {
+		chainId: ctx.config.chainId,
+		vaultAddress,
+		account,
+		currentDepositEpoch,
+		currentWithdrawalEpoch,
+		shareBalance,
+		userBasis,
+		deposit: {
+			epoch: depositEpoch,
+			queuedAssets: queuedDeposit,
+			epochState: depositEpochStateResult,
+			executable: depositEpoch < currentDepositEpoch && queuedDeposit > 0n && depositEpochStateResult.assetsFulfilled > 0n && depositEpochStateResult.sharesReceived > 0n
+		},
+		withdrawal: {
+			epoch: withdrawalEpoch,
+			queued: withdrawal,
+			epochState: withdrawalEpochStateResult,
+			executable: withdrawalEpoch < currentWithdrawalEpoch && withdrawal.amount > 0n && withdrawalEpochStateResult.sharesFulfilled > 0n && withdrawalEpochStateResult.assetsReceived > 0n
+		}
+	};
+}
+function registerListVaults(server, ctx) {
+	server.registerTool("list_vaults", {
+		title: "List HypoVaults",
+		description: "Known HypoVault deployments for a chain — vaults, managers, accountant, underlying token, pool, collateral trackers, and strategy labels.",
+		inputSchema: { chainId: z.string().optional().describe("Chain id (decimal string) to look up. Defaults to the configured chain.") }
+	}, async ({ chainId }) => {
+		const target = resolveChainId(chainId, ctx.config.chainId);
+		const vaults = getVaultRegistry(target);
+		return jsonResult({
+			chainId: target,
+			vaults,
+			liveState: target === ctx.config.chainId ? "Use vault_summary or vault_account for live vault state." : `Live state unavailable: this server is configured for chain ${ctx.config.chainId}.`
+		});
+	});
+}
+function registerVaultSummary(server, ctx) {
+	server.registerTool("vault_summary", {
+		title: "Summarize a HypoVault",
+		description: "Read live HypoVault state: supply, underlying, manager, accountant, fee wallet, fee bps, epochs, reserved withdrawal assets, and current epoch totals. Does not compute NAV/share price.",
+		inputSchema: { vaultAddress: z.string().describe("The HypoVault address on the configured chain.") }
+	}, async ({ vaultAddress }) => {
+		const vault = parseAccountAddress(vaultAddress);
+		return jsonResult(await fetchVaultSummary(ctx, vault));
+	});
+}
+function registerVaultAccount(server, ctx) {
+	server.registerTool("vault_account", {
+		title: "Inspect a HypoVault account",
+		description: "A user's HypoVault share balance, basis, queued deposit, queued withdrawal, redeposit flag, and whether selected epochs appear executable.",
+		inputSchema: {
+			vaultAddress: z.string().describe("The HypoVault address on the configured chain."),
+			address: z.string().describe("The user/account address."),
+			depositEpoch: z.string().optional().describe("Optional deposit epoch (decimal string). Defaults to current depositEpoch."),
+			withdrawalEpoch: z.string().optional().describe("Optional withdrawal epoch (decimal string). Defaults to current withdrawalEpoch.")
+		}
+	}, async ({ vaultAddress, address, depositEpoch, withdrawalEpoch }) => {
+		const vault = parseAccountAddress(vaultAddress);
+		const account = parseAccountAddress(address);
+		return jsonResult(await fetchVaultAccount(ctx, vault, account, parseOptionalDecimalBigInt(depositEpoch, "depositEpoch"), parseOptionalDecimalBigInt(withdrawalEpoch, "withdrawalEpoch")));
+	});
+}
+function registerVaultExposure(server, ctx) {
+	server.registerTool("vault_exposure", {
+		title: "Inspect HypoVault Panoptic exposure",
+		description: "Treat a HypoVault as the Panoptic account and return open positions, collateral, greeks, buying power, margin buffer, and liquidation status.",
+		inputSchema: {
+			vaultAddress: z.string().describe("The HypoVault address on the configured chain."),
+			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan.")
+		}
+	}, async ({ vaultAddress, fromBlock }) => {
+		const vault = parseAccountAddress(vaultAddress);
+		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
+		const fromBlockNumber = parseOptionalDecimalBigInt(fromBlock, "fromBlock");
+		const { poolAddress, chainId, tokenIds, storage } = await syncAccountPositions(ctx, vault, fromBlockNumber);
+		const [positions, collateral, greeks, buyingPower, marginBuffer, liquidation] = await Promise.all([
+			getPositions({
+				client: ctx.client,
+				poolAddress,
+				owner: vault,
+				tokenIds
+			}),
+			getAccountCollateral({
+				client: ctx.client,
+				poolAddress,
+				account: vault
+			}),
+			getAccountGreeks({
+				client: ctx.client,
+				chainId,
+				poolAddress,
+				account: vault,
+				storage
+			}),
+			getAccountBuyingPower({
+				client: ctx.client,
+				poolAddress,
+				account: vault,
+				tokenIds
+			}),
+			getMarginBuffer({
+				client: ctx.client,
+				poolAddress,
+				account: vault,
+				tokenIds,
+				queryAddress
+			}),
+			isLiquidatable({
+				client: ctx.client,
+				poolAddress,
+				account: vault,
+				tokenIds
+			})
+		]);
+		return jsonResult({
+			vaultAddress: vault,
+			registry: findVaultByAddress(vault, ctx.config.chainId),
+			pool: poolAddress,
+			openTokenIds: tokenIds,
+			positions,
+			collateral,
+			greeks,
+			buyingPower,
+			marginBuffer,
+			liquidation
+		});
+	});
+}
+
 //#endregion
 //#region src/tools/identifyAddress.ts
 function registerIdentifyAddress(server, ctx) {
@@ -745,7 +1399,7 @@ function registerIdentifyAddress(server, ctx) {
 			poolManager: dep.infrastructure.poolManager,
 			stateView: dep.infrastructure.stateView
 		};
-		const roles = Object.entries(candidates).filter(([, addr]) => isAddress(addr) && getAddress(addr) === needle).map(([role]) => role);
+		const roles = [...Object.entries(candidates).filter(([, addr]) => isAddress(addr) && getAddress(addr) === needle).map(([role]) => role), ...getVaultAddressRoles(needle, target)];
 		return jsonResult({
 			address: needle,
 			chainId: target,
@@ -768,15 +1422,9 @@ function registerLiquidityMap(server, ctx) {
 	}, async ({ startTick, nTicks }) => {
 		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
 		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
-		const chainId = BigInt(ctx.config.chainId);
-		const count = nTicks !== void 0 && nTicks.trim() !== "" ? BigInt(nTicks) : DEFAULT_N_TICKS;
-		const pool = await getPool({
-			client: ctx.client,
-			poolAddress,
-			chainId,
-			stateViewAddress: ctx.deployment.infrastructure.stateView
-		});
-		const start = startTick !== void 0 && startTick.trim() !== "" ? BigInt(startTick) : pool.currentTick - count / 2n * pool.tickSpacing;
+		const count = parseOptionalDecimalBigInt(nTicks, "nTicks") ?? DEFAULT_N_TICKS;
+		const pool = await getCachedPool(ctx);
+		const start = parseOptionalDecimalBigInt(startTick, "startTick", { signed: true }) ?? pool.currentTick - count / 2n * pool.tickSpacing;
 		const liquidities = await getPoolLiquidities({
 			client: ctx.client,
 			poolAddress,
@@ -834,14 +1482,14 @@ function registerListPools(server, ctx) {
 //#region src/tools/positionScenario.ts
 const DEFAULT_SPAN = 2500n;
 const DEFAULT_POINTS = 25;
-function clampTick(tick) {
-	if (tick < MIN_TICK) return MIN_TICK;
-	if (tick > MAX_TICK) return MAX_TICK;
-	return tick;
-}
-/** Human token1-per-token0 price at a tick (display float; uses token decimals). */
+const PRICE_PRECISION = 18n;
+/**
+* Human token1-per-token0 price at a tick, as a decimal string. Uses the SDK's
+* exact BigInt tick math (no Math.pow float precision loss / over/underflow at
+* extreme ticks) and applies the token-decimal scale.
+*/
 function priceAtTick(tick, decimals0, decimals1) {
-	return Math.pow(1.0001, Number(tick)) * 10 ** (Number(decimals0) - Number(decimals1));
+	return tickToPriceDecimalScaled(tick, decimals0, decimals1, PRICE_PRECISION);
 }
 function registerPositionScenario(server, ctx) {
 	server.registerTool("position_scenario", {
@@ -856,17 +1504,11 @@ function registerPositionScenario(server, ctx) {
 			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan.")
 		}
 	}, async ({ address, startTick, endTick, points, includePendingPremium, fromBlock }) => {
-		if (!isAddress(address)) throw new Error(`Invalid address: ${address}`);
-		const account = getAddress(address);
+		const account = parseAccountAddress(address);
 		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
 		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
-		const pool = await getPool({
-			client: ctx.client,
-			poolAddress,
-			chainId: BigInt(ctx.config.chainId),
-			stateViewAddress: ctx.deployment.infrastructure.stateView
-		});
-		const { tokenIds } = await syncAccountPositions(ctx, account, fromBlock ? BigInt(fromBlock) : void 0);
+		const pool = await getCachedPool(ctx);
+		const { tokenIds } = await syncAccountPositions(ctx, account, parseOptionalDecimalBigInt(fromBlock, "fromBlock"));
 		if (tokenIds.length === 0) return jsonResult({
 			account,
 			pool: poolAddress,
@@ -875,8 +1517,10 @@ function registerPositionScenario(server, ctx) {
 			note: "Account has no open positions on this pool; nothing to evaluate."
 		});
 		const n = points ?? DEFAULT_POINTS;
-		const start = clampTick(startTick !== void 0 ? BigInt(startTick) : pool.currentTick - DEFAULT_SPAN);
-		const end = clampTick(endTick !== void 0 ? BigInt(endTick) : pool.currentTick + DEFAULT_SPAN);
+		const startTickValue = parseOptionalDecimalBigInt(startTick, "startTick", { signed: true });
+		const endTickValue = parseOptionalDecimalBigInt(endTick, "endTick", { signed: true });
+		const start = clampTick(startTickValue ?? pool.currentTick - DEFAULT_SPAN);
+		const end = clampTick(endTickValue ?? pool.currentTick + DEFAULT_SPAN);
 		const span = Number(end - start);
 		const atTicks = [];
 		for (let i = 0; i < n; i++) atTicks.push(clampTick(start + BigInt(Math.round(i * span / (n - 1)))));
@@ -928,23 +1572,12 @@ function registerPreviewPosition(server, ctx) {
 			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan.")
 		}
 	}, async ({ address, tokenId, positionSize, tickLimitLow, tickLimitHigh, swapAtMint, usePremiaAsCollateral, fromBlock }) => {
-		if (!isAddress(address)) throw new Error(`Invalid address: ${address}`);
-		const account = getAddress(address);
-		let id;
-		let size;
-		try {
-			id = BigInt(tokenId.trim());
-		} catch {
-			throw new Error(`Invalid tokenId (expected a 0x-hex or decimal string): ${tokenId}`);
-		}
-		try {
-			size = BigInt(positionSize);
-		} catch {
-			throw new Error(`Invalid positionSize (expected a decimal string): ${positionSize}`);
-		}
+		const account = parseAccountAddress(address);
+		const id = parseTokenId(tokenId);
+		const size = parseDecimalBigInt(positionSize, "positionSize");
 		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
 		const queryAddress = ctx.deployment.panoptic.v2.panopticQuery;
-		const { tokenIds } = await syncAccountPositions(ctx, account, fromBlock ? BigInt(fromBlock) : void 0);
+		const { tokenIds } = await syncAccountPositions(ctx, account, parseOptionalDecimalBigInt(fromBlock, "fromBlock"));
 		const preview = await getOpenPositionPreview({
 			client: ctx.client,
 			poolAddress,
@@ -953,8 +1586,8 @@ function registerPreviewPosition(server, ctx) {
 			tokenId: id,
 			positionSize: size,
 			queryAddress,
-			tickLimitLow: tickLimitLow !== void 0 ? BigInt(tickLimitLow) : MIN_TICK,
-			tickLimitHigh: tickLimitHigh !== void 0 ? BigInt(tickLimitHigh) : MAX_TICK,
+			tickLimitLow: parseOptionalDecimalBigInt(tickLimitLow, "tickLimitLow", { signed: true }) ?? MIN_TICK,
+			tickLimitHigh: parseOptionalDecimalBigInt(tickLimitHigh, "tickLimitHigh", { signed: true }) ?? MAX_TICK,
 			swapAtMint: swapAtMint ?? false,
 			usePremiaAsCollateral: usePremiaAsCollateral ?? false
 		});
@@ -982,34 +1615,30 @@ function registerPreviewPosition(server, ctx) {
 
 //#endregion
 //#region src/tools/suggestDeltaHedge.ts
-/** Align a tick down to the nearest multiple of tickSpacing (matches buildUniqueLoan). */
-function alignStrike(tick, tickSpacing) {
-	const mod = (tick % tickSpacing + tickSpacing) % tickSpacing;
-	return tick - mod;
-}
 function registerSuggestDeltaHedge(server, ctx) {
 	server.registerTool("suggest_delta_hedge", {
 		title: "Suggest a delta-neutral hedge",
 		description: "Compute an account's net delta on the configured pool (option positions + deposited collateral) and suggest a Panoptic width=0 loan/credit leg that neutralizes it. A width=0 leg carries pure, spot-like directional delta (delta = ±size, no gamma): a LOAN borrowing the asset adds short delta, a CREDIT lending the asset adds long delta. If the account is net LONG the asset, the tool suggests a loan; if net SHORT, a credit. Returns an inspectable explicit-leg suggestion (tokenId + size) that can be handed to build_position; it does not execute anything.",
 		inputSchema: {
 			address: z.string().describe("The account address."),
-			assetIndex: z.union([z.literal(0), z.literal(1)]).optional().describe("Which token is the directional asset (0 or 1). Defaults to inferring the non-stablecoin token from pool symbols."),
+			assetIndex: z.union([z.literal(0), z.literal(1)]).optional().describe("Reporting frame for the aggregate net delta: 0 = token0 units, 1 = token1 units. This is a denomination choice (it overrides each leg's own asset when aggregating), NOT a canonical pool asset. If omitted and no session preference is set (via configure_session), the tool asks the user which token to use instead of guessing."),
 			fromBlock: z.string().optional().describe("Optional starting block (decimal string) to bound the position event scan.")
 		}
 	}, async ({ address, assetIndex, fromBlock }) => {
-		if (!isAddress(address)) throw new Error(`Invalid address: ${address}`);
-		const account = getAddress(address);
+		const account = parseAccountAddress(address);
 		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
 		const chainId = BigInt(ctx.config.chainId);
-		const pool = await getPool({
-			client: ctx.client,
-			poolAddress,
-			chainId,
-			stateViewAddress: ctx.deployment.infrastructure.stateView
+		const pool = await getCachedPool(ctx);
+		const frameResolution = resolveDeltaFrame(pool, assetIndex, ctx.session.preferredAssetIndex);
+		if (frameResolution.needsUserChoice) return assetPreferenceRequired({
+			token0: pool.collateralTracker0.symbol,
+			token1: pool.collateralTracker1.symbol,
+			suggestedAssetIndex: frameResolution.frame,
+			suggestionReason: frameResolution.reason
 		});
-		const { asset, inferred: assetInferred } = inferAssetIndex(pool, assetIndex);
+		const { frame: asset, source: assetFrameSource, reason: assetFrameReason } = frameResolution;
 		const assetSymbol = asset === 0n ? pool.collateralTracker0.symbol : pool.collateralTracker1.symbol;
-		const { tokenIds, storage } = await syncAccountPositions(ctx, account, fromBlock ? BigInt(fromBlock) : void 0);
+		const { tokenIds, storage } = await syncAccountPositions(ctx, account, parseOptionalDecimalBigInt(fromBlock, "fromBlock"));
 		const greeks = await getAccountGreeks({
 			client: ctx.client,
 			chainId,
@@ -1025,12 +1654,17 @@ function registerSuggestDeltaHedge(server, ctx) {
 			pool: poolAddress,
 			assetIndex: asset,
 			assetSymbol,
-			assetInferred,
+			deltaFrame: {
+				assetIndex: asset,
+				symbol: assetSymbol,
+				source: assetFrameSource,
+				reason: assetFrameReason
+			},
 			openTokenIds: tokenIds,
 			positionsDelta: greeks.positionsDelta,
 			collateralDelta: greeks.collateralDelta,
 			netDelta,
-			netDeltaNote: `Net delta is expressed in ${assetSymbol} smallest units (positive = net long the asset).`
+			netDeltaNote: `Net delta is expressed in ${assetSymbol} smallest units (positive = net long ${assetSymbol}). ${DELTA_FRAME_NOTE}`
 		};
 		if (netDelta === 0n) return jsonResult({
 			...facts,
@@ -1039,7 +1673,7 @@ function registerSuggestDeltaHedge(server, ctx) {
 		});
 		const isLoan = netDelta > 0n;
 		const size = netDelta > 0n ? netDelta : -netDelta;
-		const strike = alignStrike(pool.currentTick, pool.tickSpacing);
+		const strike = roundToTickSpacing(pool.currentTick, pool.tickSpacing);
 		const builder = createTokenIdBuilder(pool.poolId);
 		const legConfig = {
 			asset,
@@ -1084,20 +1718,25 @@ function registerTradeHistory(server, ctx) {
 	}, async ({ address, fromBlock, toBlock }) => {
 		const account = parseAccountAddress(address);
 		const poolAddress = ctx.deployment.panoptic.pool.panopticPool;
-		const hasFrom = fromBlock !== void 0 && fromBlock.trim() !== "";
-		const hasTo = toBlock !== void 0 && toBlock.trim() !== "";
-		const start = hasFrom ? BigInt(fromBlock) : await getPoolDeploymentBlock(ctx.client, poolAddress) ?? 0n;
+		const fromBlockArg = parseOptionalDecimalBigInt(fromBlock, "fromBlock");
+		const toBlockArg = parseOptionalDecimalBigInt(toBlock, "toBlock");
+		const deploymentBlock = fromBlockArg !== void 0 ? void 0 : await getPoolDeploymentBlock(ctx.client, poolAddress);
+		const start = fromBlockArg ?? deploymentBlock ?? 0n;
+		const fromBlockSource = fromBlockArg !== void 0 ? "caller" : deploymentBlock !== void 0 && deploymentBlock !== null ? "pool-deployment-block" : "fallback-zero";
 		const history = await getAccountHistory({
 			client: ctx.client,
 			poolAddress,
 			account,
 			fromBlock: start,
-			toBlock: hasTo ? BigInt(toBlock) : void 0
+			toBlock: toBlockArg
 		});
 		return jsonResult({
 			account,
 			pool: poolAddress,
 			fromBlock: start,
+			fromBlockSource,
+			toBlock: toBlockArg,
+			...fromBlockSource === "fallback-zero" ? { scanWarning: "Pool deployment block could not be resolved; scanning from block 0. History may be incomplete or truncated by the RPC provider. Pass fromBlock to bound the scan." } : {},
 			tradeCount: history.trades.length,
 			trades: history.trades,
 			_meta: history._meta
@@ -1120,6 +1759,7 @@ function createServer(ctx) {
 		name: SERVER_NAME,
 		version: SERVER_VERSION
 	});
+	registerConfigureSession(server, ctx);
 	registerListPools(server, ctx);
 	registerExplainPosition(server, ctx);
 	registerIdentifyAddress(server, ctx);
@@ -1133,6 +1773,10 @@ function createServer(ctx) {
 	registerPositionScenario(server, ctx);
 	registerHedgeParams(server, ctx);
 	registerTradeHistory(server, ctx);
+	registerListVaults(server, ctx);
+	registerVaultSummary(server, ctx);
+	registerVaultAccount(server, ctx);
+	registerVaultExposure(server, ctx);
 	return server;
 }