chain-insights 0.2.16

package/dist/resolver-C2ZS7oC8.mjs

@@ -0,0 +1,201 @@
+import path from "node:path";
+import { readFile, readdir } from "node:fs/promises";
+import os from "node:os";
+const BUILTIN_PLAYBOOKS = {
+	"trace-funds": `---
+name: trace-funds
+description: Trace stolen funds from a victim address to exchange deposits using Chain Insights GraphRAG
+version: 1.0.0
+params:
+  - name: address
+    type: string
+    required: true
+  - name: network
+    type: string
+    required: false
+    default: bittensor
+---
+
+## Step 1: Screen Victim Address
+
+\`\`\`tool
+address_risk
+\`\`\`
+
+\`\`\`params
+address: {{address}}
+network: {{network}}
+\`\`\`
+
+## Step 2: Trace Funds To Exchanges
+
+\`\`\`tool
+track_funds
+\`\`\`
+
+\`\`\`params
+trusted_addresses: {{address}}
+network: {{network}}
+\`\`\`
+`,
+	"scam-topology": `---
+name: scam-topology
+description: Build laundering topology and scam labels from a victim incident
+version: 1.0.0
+params:
+  - name: address
+    type: string
+    required: true
+  - name: incident_timestamp_ms
+    type: string
+    required: true
+  - name: network
+    type: string
+    required: false
+    default: bittensor
+  - name: activity_policy
+    type: string
+    required: false
+    default: node_relative_only
+---
+
+## Step 1: Screen Known Scam Address
+
+\`\`\`tool
+address_risk
+\`\`\`
+
+\`\`\`params
+address: {{address}}
+network: {{network}}
+\`\`\`
+
+## Step 2: Build Scam Topology
+
+The victim-only traversal is outward from victim/source funds. The
+primary traversal is a node-relative novelty wave: each new node expands only
+once, repeated targets remain as non-expanding convergence context, and
+downstream edges must be active at or after the current node's wave-arrival
+timestamp. Set activity_policy to global_incident_only to filter every wave
+against incident_timestamp_ms instead. Exchange terminal safety stops exchange
+endpoints, and label candidates are reviewable, not automatic writes.
+Contract summary: victim-only traversal is outward from victim/source funds;
+node-relative novelty wave by default; global_incident_only is available;
+exchange terminal safety; scam_labels are ML-ready flags.
+
+\`\`\`tool
+scam_topology
+\`\`\`
+
+\`\`\`params
+victim_address: {{address}}
+incident_timestamp_ms: {{incident_timestamp_ms}}
+network: {{network}}
+activity_policy: {{activity_policy}}
+\`\`\`
+`,
+	"risk-check": `---
+name: risk-check
+description: Screen an address for Chain Insights risk, behavior, counterparties, exchange connections, and AML patterns
+version: 1.0.0
+params:
+  - name: address
+    type: string
+    required: true
+  - name: network
+    type: string
+    required: false
+    default: bittensor
+---
+
+## Step 1: Address Risk
+
+\`\`\`tool
+address_risk
+\`\`\`
+
+\`\`\`params
+address: {{address}}
+network: {{network}}
+\`\`\`
+`,
+	"entity-profile": `---
+name: entity-profile
+description: Build an entity profile from Chain Insights address identity, metrics, risk, counterparties, and labels
+version: 1.0.0
+params:
+  - name: address
+    type: string
+    required: true
+  - name: network
+    type: string
+    required: false
+    default: bittensor
+---
+
+## Step 1: Entity Profile
+
+\`\`\`tool
+address_risk
+\`\`\`
+
+\`\`\`params
+address: {{address}}
+network: {{network}}
+\`\`\`
+`
+};
+//#endregion
+//#region src/playbooks/resolver.ts
+function userDir() {
+	return path.join(os.homedir(), ".chain-insights", "playbooks");
+}
+/**
+* Resolve a playbook name to its markdown content.
+* Checks user directory (~/.chain-insights/playbooks/<name>.md) first,
+* then falls back to the built-in BUILTIN_PLAYBOOKS map.
+* Security: sanitizes name to prevent path traversal (T-05-01).
+*/
+async function resolvePlaybookContent(name) {
+	const safeName = name.replace(/[^a-z0-9_-]/gi, "");
+	if (!safeName) throw new Error(`Invalid playbook name: ${name}`);
+	const userPath = path.join(userDir(), `${safeName}.md`);
+	try {
+		return await readFile(userPath, "utf8");
+	} catch {}
+	const builtin = BUILTIN_PLAYBOOKS[safeName];
+	if (builtin !== void 0) return builtin;
+	throw new Error(`Playbook not found: "${safeName}". Run \`chain-insights playbook list\` to see available playbooks.`);
+}
+/**
+* List all available playbooks — user dir first (overrides), then built-ins.
+* Returns array of { name, source } objects.
+*/
+async function listPlaybooks() {
+	const result = [];
+	const seen = /* @__PURE__ */ new Set();
+	try {
+		const userFiles = await readdir(userDir());
+		for (const file of userFiles) {
+			if (!file.endsWith(".md")) continue;
+			const name = file.slice(0, -3);
+			seen.add(name);
+			result.push({
+				name,
+				source: "user"
+			});
+		}
+	} catch {}
+	for (const name of Object.keys(BUILTIN_PLAYBOOKS)) {
+		if (seen.has(name)) continue;
+		result.push({
+			name,
+			source: "builtin"
+		});
+	}
+	return result;
+}
+//#endregion
+export { listPlaybooks, resolvePlaybookContent };
+
+//# sourceMappingURL=resolver-C2ZS7oC8.mjs.map

package/dist/resolver-C2ZS7oC8.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver-C2ZS7oC8.mjs","names":[],"sources":["../src/playbooks/builtins.ts","../src/playbooks/resolver.ts"],"sourcesContent":["// Built-in playbook definitions tied to the current GraphRAG public MCP tools.\n// Source of truth inspected in rbmk/repos/ml/graphrag/src/mcp_server/tools.\n\nexport const KNOWN_GRAPHRAG_PUBLIC_TOOLS = [\n  'address_risk',\n  'scam_topology',\n  'track_funds',\n  'graph_query',\n  'graph_query_batch',\n] as const\n\nexport const TRACE_FUNDS_PLAYBOOK = `---\nname: trace-funds\ndescription: Trace stolen funds from a victim address to exchange deposits using Chain Insights GraphRAG\nversion: 1.0.0\nparams:\n  - name: address\n    type: string\n    required: true\n  - name: network\n    type: string\n    required: false\n    default: bittensor\n---\n\n## Step 1: Screen Victim Address\n\n\\`\\`\\`tool\naddress_risk\n\\`\\`\\`\n\n\\`\\`\\`params\naddress: {{address}}\nnetwork: {{network}}\n\\`\\`\\`\n\n## Step 2: Trace Funds To Exchanges\n\n\\`\\`\\`tool\ntrack_funds\n\\`\\`\\`\n\n\\`\\`\\`params\ntrusted_addresses: {{address}}\nnetwork: {{network}}\n\\`\\`\\`\n`\n\nexport const RISK_CHECK_PLAYBOOK = `---\nname: risk-check\ndescription: Screen an address for Chain Insights risk, behavior, counterparties, exchange connections, and AML patterns\nversion: 1.0.0\nparams:\n  - name: address\n    type: string\n    required: true\n  - name: network\n    type: string\n    required: false\n    default: bittensor\n---\n\n## Step 1: Address Risk\n\n\\`\\`\\`tool\naddress_risk\n\\`\\`\\`\n\n\\`\\`\\`params\naddress: {{address}}\nnetwork: {{network}}\n\\`\\`\\`\n`\n\nexport const ENTITY_PROFILE_PLAYBOOK = `---\nname: entity-profile\ndescription: Build an entity profile from Chain Insights address identity, metrics, risk, counterparties, and labels\nversion: 1.0.0\nparams:\n  - name: address\n    type: string\n    required: true\n  - name: network\n    type: string\n    required: false\n    default: bittensor\n---\n\n## Step 1: Entity Profile\n\n\\`\\`\\`tool\naddress_risk\n\\`\\`\\`\n\n\\`\\`\\`params\naddress: {{address}}\nnetwork: {{network}}\n\\`\\`\\`\n`\n\nexport const SCAM_TOPOLOGY_PLAYBOOK = `---\nname: scam-topology\ndescription: Build laundering topology and scam labels from a victim incident\nversion: 1.0.0\nparams:\n  - name: address\n    type: string\n    required: true\n  - name: incident_timestamp_ms\n    type: string\n    required: true\n  - name: network\n    type: string\n    required: false\n    default: bittensor\n  - name: activity_policy\n    type: string\n    required: false\n    default: node_relative_only\n---\n\n## Step 1: Screen Known Scam Address\n\n\\`\\`\\`tool\naddress_risk\n\\`\\`\\`\n\n\\`\\`\\`params\naddress: {{address}}\nnetwork: {{network}}\n\\`\\`\\`\n\n## Step 2: Build Scam Topology\n\nThe victim-only traversal is outward from victim/source funds. The\nprimary traversal is a node-relative novelty wave: each new node expands only\nonce, repeated targets remain as non-expanding convergence context, and\ndownstream edges must be active at or after the current node's wave-arrival\ntimestamp. Set activity_policy to global_incident_only to filter every wave\nagainst incident_timestamp_ms instead. Exchange terminal safety stops exchange\nendpoints, and label candidates are reviewable, not automatic writes.\nContract summary: victim-only traversal is outward from victim/source funds;\nnode-relative novelty wave by default; global_incident_only is available;\nexchange terminal safety; scam_labels are ML-ready flags.\n\n\\`\\`\\`tool\nscam_topology\n\\`\\`\\`\n\n\\`\\`\\`params\nvictim_address: {{address}}\nincident_timestamp_ms: {{incident_timestamp_ms}}\nnetwork: {{network}}\nactivity_policy: {{activity_policy}}\n\\`\\`\\`\n`\n\nexport const BUILTIN_PLAYBOOKS: Record<string, string> = {\n  'trace-funds':    TRACE_FUNDS_PLAYBOOK,\n  'scam-topology':  SCAM_TOPOLOGY_PLAYBOOK,\n  'risk-check':     RISK_CHECK_PLAYBOOK,\n  'entity-profile': ENTITY_PROFILE_PLAYBOOK,\n}\n","import path from 'node:path'\nimport { access, readFile, readdir } from 'node:fs/promises'\nimport os from 'node:os'\nimport { BUILTIN_PLAYBOOKS } from './builtins.js'\n\nfunction userDir(): string {\n  return path.join(os.homedir(), '.chain-insights', 'playbooks')\n}\n\n/**\n * Resolve a playbook name to its absolute file path.\n * Checks user directory (~/.chain-insights/playbooks/) first, then built-in directory.\n * Security: sanitizes name to prevent path traversal (T-05-01).\n *\n * @deprecated Prefer resolvePlaybookContent() which returns markdown directly.\n */\nexport async function resolvePlaybook(name: string): Promise<string> {\n  // Security: sanitize name to prevent path traversal (per security threat T-05-01)\n  const safeName = name.replace(/[^a-z0-9_-]/gi, '')\n  if (!safeName) throw new Error(`Invalid playbook name: ${name}`)\n\n  const userPath = path.join(userDir(), `${safeName}.md`)\n\n  try {\n    await access(userPath)\n    return userPath\n  } catch {\n    // Fall through to built-in check\n  }\n\n  // Check built-in playbooks map (T-05-01: no filesystem path exposure for built-ins)\n  if (safeName in BUILTIN_PLAYBOOKS) {\n    // Return a sentinel path for legacy callers — content comes from BUILTIN_PLAYBOOKS\n    return `builtin:${safeName}`\n  }\n\n  throw new Error(\n    `Playbook not found: \"${safeName}\". Run \\`chain-insights playbook list\\` to see available playbooks.`\n  )\n}\n\n/**\n * Resolve a playbook name to its markdown content.\n * Checks user directory (~/.chain-insights/playbooks/<name>.md) first,\n * then falls back to the built-in BUILTIN_PLAYBOOKS map.\n * Security: sanitizes name to prevent path traversal (T-05-01).\n */\nexport async function resolvePlaybookContent(name: string): Promise<string> {\n  // Security: sanitize name to prevent path traversal (per security threat T-05-01)\n  const safeName = name.replace(/[^a-z0-9_-]/gi, '')\n  if (!safeName) throw new Error(`Invalid playbook name: ${name}`)\n\n  // 1. Check user directory first (user playbooks override built-ins)\n  const userPath = path.join(userDir(), `${safeName}.md`)\n  try {\n    return await readFile(userPath, 'utf8')\n  } catch {\n    // Not in user dir — fall through\n  }\n\n  // 2. Fall back to built-in map\n  const builtin = BUILTIN_PLAYBOOKS[safeName]\n  if (builtin !== undefined) return builtin\n\n  throw new Error(\n    `Playbook not found: \"${safeName}\". Run \\`chain-insights playbook list\\` to see available playbooks.`\n  )\n}\n\n/**\n * List all available playbooks — user dir first (overrides), then built-ins.\n * Returns array of { name, source } objects.\n */\nexport async function listPlaybooks(): Promise<Array<{ name: string; source: 'builtin' | 'user' }>> {\n  const result: Array<{ name: string; source: 'builtin' | 'user' }> = []\n  const seen = new Set<string>()\n\n  // User playbooks first\n  try {\n    const userFiles = await readdir(userDir())\n    for (const file of userFiles) {\n      if (!file.endsWith('.md')) continue\n      const name = file.slice(0, -3) // remove .md\n      seen.add(name)\n      result.push({ name, source: 'user' })\n    }\n  } catch {\n    // User dir doesn't exist — that's fine\n  }\n\n  // Built-in playbooks from the embedded map (not filesystem)\n  for (const name of Object.keys(BUILTIN_PLAYBOOKS)) {\n    if (seen.has(name)) continue // user override takes precedence\n    result.push({ name, source: 'builtin' })\n  }\n\n  return result\n}\n"],"mappings":";;;AA6JA,MAAa,oBAA4C;CACvD,eAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAClB,iBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAClB,cAAkB;;;;;;;;;;;;;;;;;;;;;;;;;CAClB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;CACnB;;;AC7JD,SAAS,UAAkB;AACzB,QAAO,KAAK,KAAK,GAAG,SAAS,EAAE,mBAAmB,YAAY;;;;;;;;AAyChE,eAAsB,uBAAuB,MAA+B;CAE1E,MAAM,WAAW,KAAK,QAAQ,iBAAiB,GAAG;AAClD,KAAI,CAAC,SAAU,OAAM,IAAI,MAAM,0BAA0B,OAAO;CAGhE,MAAM,WAAW,KAAK,KAAK,SAAS,EAAE,GAAG,SAAS,KAAK;AACvD,KAAI;AACF,SAAO,MAAM,SAAS,UAAU,OAAO;SACjC;CAKR,MAAM,UAAU,kBAAkB;AAClC,KAAI,YAAY,KAAA,EAAW,QAAO;AAElC,OAAM,IAAI,MACR,wBAAwB,SAAS,qEAClC;;;;;;AAOH,eAAsB,gBAA8E;CAClG,MAAM,SAA8D,EAAE;CACtE,MAAM,uBAAO,IAAI,KAAa;AAG9B,KAAI;EACF,MAAM,YAAY,MAAM,QAAQ,SAAS,CAAC;AAC1C,OAAK,MAAM,QAAQ,WAAW;AAC5B,OAAI,CAAC,KAAK,SAAS,MAAM,CAAE;GAC3B,MAAM,OAAO,KAAK,MAAM,GAAG,GAAG;AAC9B,QAAK,IAAI,KAAK;AACd,UAAO,KAAK;IAAE;IAAM,QAAQ;IAAQ,CAAC;;SAEjC;AAKR,MAAK,MAAM,QAAQ,OAAO,KAAK,kBAAkB,EAAE;AACjD,MAAI,KAAK,IAAI,KAAK,CAAE;AACpB,SAAO,KAAK;GAAE;GAAM,QAAQ;GAAW,CAAC;;AAG1C,QAAO"}

package/dist/resolver-zYbu4wDV.cjs

@@ -0,0 +1,203 @@
+const require_chunk = require("./chunk-CZWwpsFl.cjs");
+let node_path = require("node:path");
+node_path = require_chunk.__toESM(node_path, 1);
+let node_fs_promises = require("node:fs/promises");
+let node_os = require("node:os");
+node_os = require_chunk.__toESM(node_os, 1);
+const BUILTIN_PLAYBOOKS = {
+	"trace-funds": `---
+name: trace-funds
+description: Trace stolen funds from a victim address to exchange deposits using Chain Insights GraphRAG
+version: 1.0.0
+params:
+  - name: address
+    type: string
+    required: true
+  - name: network
+    type: string
+    required: false
+    default: bittensor
+---
+
+## Step 1: Screen Victim Address
+
+\`\`\`tool
+address_risk
+\`\`\`
+
+\`\`\`params
+address: {{address}}
+network: {{network}}
+\`\`\`
+
+## Step 2: Trace Funds To Exchanges
+
+\`\`\`tool
+track_funds
+\`\`\`
+
+\`\`\`params
+trusted_addresses: {{address}}
+network: {{network}}
+\`\`\`
+`,
+	"scam-topology": `---
+name: scam-topology
+description: Build laundering topology and scam labels from a victim incident
+version: 1.0.0
+params:
+  - name: address
+    type: string
+    required: true
+  - name: incident_timestamp_ms
+    type: string
+    required: true
+  - name: network
+    type: string
+    required: false
+    default: bittensor
+  - name: activity_policy
+    type: string
+    required: false
+    default: node_relative_only
+---
+
+## Step 1: Screen Known Scam Address
+
+\`\`\`tool
+address_risk
+\`\`\`
+
+\`\`\`params
+address: {{address}}
+network: {{network}}
+\`\`\`
+
+## Step 2: Build Scam Topology
+
+The victim-only traversal is outward from victim/source funds. The
+primary traversal is a node-relative novelty wave: each new node expands only
+once, repeated targets remain as non-expanding convergence context, and
+downstream edges must be active at or after the current node's wave-arrival
+timestamp. Set activity_policy to global_incident_only to filter every wave
+against incident_timestamp_ms instead. Exchange terminal safety stops exchange
+endpoints, and label candidates are reviewable, not automatic writes.
+Contract summary: victim-only traversal is outward from victim/source funds;
+node-relative novelty wave by default; global_incident_only is available;
+exchange terminal safety; scam_labels are ML-ready flags.
+
+\`\`\`tool
+scam_topology
+\`\`\`
+
+\`\`\`params
+victim_address: {{address}}
+incident_timestamp_ms: {{incident_timestamp_ms}}
+network: {{network}}
+activity_policy: {{activity_policy}}
+\`\`\`
+`,
+	"risk-check": `---
+name: risk-check
+description: Screen an address for Chain Insights risk, behavior, counterparties, exchange connections, and AML patterns
+version: 1.0.0
+params:
+  - name: address
+    type: string
+    required: true
+  - name: network
+    type: string
+    required: false
+    default: bittensor
+---
+
+## Step 1: Address Risk
+
+\`\`\`tool
+address_risk
+\`\`\`
+
+\`\`\`params
+address: {{address}}
+network: {{network}}
+\`\`\`
+`,
+	"entity-profile": `---
+name: entity-profile
+description: Build an entity profile from Chain Insights address identity, metrics, risk, counterparties, and labels
+version: 1.0.0
+params:
+  - name: address
+    type: string
+    required: true
+  - name: network
+    type: string
+    required: false
+    default: bittensor
+---
+
+## Step 1: Entity Profile
+
+\`\`\`tool
+address_risk
+\`\`\`
+
+\`\`\`params
+address: {{address}}
+network: {{network}}
+\`\`\`
+`
+};
+//#endregion
+//#region src/playbooks/resolver.ts
+function userDir() {
+	return node_path.default.join(node_os.default.homedir(), ".chain-insights", "playbooks");
+}
+/**
+* Resolve a playbook name to its markdown content.
+* Checks user directory (~/.chain-insights/playbooks/<name>.md) first,
+* then falls back to the built-in BUILTIN_PLAYBOOKS map.
+* Security: sanitizes name to prevent path traversal (T-05-01).
+*/
+async function resolvePlaybookContent(name) {
+	const safeName = name.replace(/[^a-z0-9_-]/gi, "");
+	if (!safeName) throw new Error(`Invalid playbook name: ${name}`);
+	const userPath = node_path.default.join(userDir(), `${safeName}.md`);
+	try {
+		return await (0, node_fs_promises.readFile)(userPath, "utf8");
+	} catch {}
+	const builtin = BUILTIN_PLAYBOOKS[safeName];
+	if (builtin !== void 0) return builtin;
+	throw new Error(`Playbook not found: "${safeName}". Run \`chain-insights playbook list\` to see available playbooks.`);
+}
+/**
+* List all available playbooks — user dir first (overrides), then built-ins.
+* Returns array of { name, source } objects.
+*/
+async function listPlaybooks() {
+	const result = [];
+	const seen = /* @__PURE__ */ new Set();
+	try {
+		const userFiles = await (0, node_fs_promises.readdir)(userDir());
+		for (const file of userFiles) {
+			if (!file.endsWith(".md")) continue;
+			const name = file.slice(0, -3);
+			seen.add(name);
+			result.push({
+				name,
+				source: "user"
+			});
+		}
+	} catch {}
+	for (const name of Object.keys(BUILTIN_PLAYBOOKS)) {
+		if (seen.has(name)) continue;
+		result.push({
+			name,
+			source: "builtin"
+		});
+	}
+	return result;
+}
+//#endregion
+exports.listPlaybooks = listPlaybooks;
+exports.resolvePlaybookContent = resolvePlaybookContent;

package/dist/rolldown-runtime-wcPFST8Q.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/dist/runner-1Eq55OYb.cjs

@@ -0,0 +1,148 @@
+require("./chunk-CZWwpsFl.cjs");
+const require_version = require("./version-BNGtdpmH.cjs");
+const require_config = require("./config-Bmdl5hdk.cjs");
+const require_client = require("./client-D4fZgIaO.cjs");
+const require_viz = require("./viz-ClezVXrJ.cjs");
+const require_store = require("./store-BiUhQOIf.cjs");
+const require_evidence = require("./evidence-BGcdKxuV.cjs");
+let _modelcontextprotocol_sdk_client_index_js = require("@modelcontextprotocol/sdk/client/index.js");
+let _modelcontextprotocol_sdk_client_streamableHttp_js = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
+//#region src/playbooks/runner.ts
+/** Sleep for ms milliseconds. */
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Check if an error is a timeout/abort error. */
+function isTimeoutError(err) {
+	if (!(err instanceof Error)) return false;
+	return err.name === "AbortError" || err.code === "ECONNRESET";
+}
+/** Check if an error is a payment failure. */
+function isPaymentError(err) {
+	if (!(err instanceof Error)) return false;
+	const msg = err.message.toLowerCase();
+	return msg.includes("http 402") || msg.includes("status 402") || msg.includes("payment required") || msg.includes("x402");
+}
+/**
+* Call an MCP tool with retry logic on timeout (up to 3 total attempts).
+* Returns the text result or throws on non-retryable error.
+*/
+async function callWithRetry(client, toolName, params) {
+	const MAX_ATTEMPTS = 3;
+	let lastErr;
+	for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) try {
+		return (await client.callTool({
+			name: toolName,
+			arguments: params
+		})).content.filter((c) => c.type === "text").map((c) => c.text ?? "").join("\n");
+	} catch (err) {
+		if (isTimeoutError(err) && attempt < MAX_ATTEMPTS) {
+			lastErr = err;
+			await sleep(1e3);
+			continue;
+		}
+		throw err;
+	}
+	throw lastErr;
+}
+async function validateStepTools(client, steps) {
+	const result = await client.listTools();
+	const available = new Set(result.tools.map((tool) => tool.name));
+	const missing = [...new Set(steps.map((step) => step.tool).filter((tool) => !available.has(tool)))];
+	if (missing.length === 0) return;
+	const availableList = [...available].sort().join(", ") || "none";
+	throw new Error(`Unknown MCP tool(s) in playbook: ${missing.join(", ")}. Available tools: ${availableList}. Run \`chain-insights mcp tools --refresh\` to inspect the live MCP schema.`);
+}
+const PlaybookRunner = { 
+/**
+* Execute a playbook definition step-by-step against the live MCP.
+*
+* @param playbook - Parsed and validated PlaybookDefinition
+* @param opts     - Runner options (caseId, from, dryRun, params)
+*/
+async run(playbook, opts) {
+	const startIndex = (opts.from ?? 1) - 1;
+	const stepsToRun = playbook.steps.slice(startIndex);
+	const totalSteps = playbook.steps.length;
+	if (opts.dryRun) {
+		console.log(`Playbook: ${playbook.name} (dry run — no MCP calls)`);
+		console.log(`Steps: ${totalSteps} total, starting from ${startIndex + 1}`);
+		console.log("");
+		for (const step of stepsToRun) console.log(`Step ${step.index}/${totalSteps}: ${step.tool} (params: ${JSON.stringify(step.params)})`);
+		console.log("");
+		console.log("Cost: unknown (MCP pricing not available without live connection)");
+		return;
+	}
+	const config = await require_config.loadConfig();
+	const mcpFetch = await require_client.createConfiguredMcpFetch(config);
+	let caseId;
+	if (opts.caseId) caseId = (await require_store.CaseStore.get(opts.caseId)).id;
+	else {
+		caseId = (await require_store.CaseStore.create({
+			name: `quick-${playbook.name}-${Date.now()}`,
+			tags: [
+				"quick",
+				"playbook",
+				playbook.name
+			],
+			description: `Auto-created for one-off playbook run: ${playbook.name}`
+		})).id;
+		console.log(`Created quick case: ${caseId}`);
+	}
+	const client = new _modelcontextprotocol_sdk_client_index_js.Client({
+		name: "chain-insights-playbook",
+		version: require_version.PACKAGE_VERSION
+	});
+	await client.connect(new _modelcontextprotocol_sdk_client_streamableHttp_js.StreamableHTTPClientTransport(new URL(config.mcpEndpoint), { fetch: mcpFetch }));
+	let evidenceCount = 0;
+	try {
+		await validateStepTools(client, stepsToRun);
+		for (const step of stepsToRun) {
+			console.log(`Step ${step.index}/${totalSteps}: ${step.label}...`);
+			let result;
+			try {
+				result = await callWithRetry(client, step.tool, step.params);
+			} catch (err) {
+				if (isPaymentError(err)) if (process.stdin.isTTY) {
+					const { createInterface } = await import("node:readline");
+					const rl = createInterface({
+						input: process.stdin,
+						output: process.stdout
+					});
+					const answer = await new Promise((resolve) => {
+						rl.question(`Payment required for step ${step.index}. (retry/skip/abort): `, resolve);
+					});
+					rl.close();
+					if (answer.trim().toLowerCase() === "retry") result = await callWithRetry(client, step.tool, step.params);
+					else if (answer.trim().toLowerCase() === "skip") {
+						console.log(`Step ${step.index} skipped.`);
+						continue;
+					} else throw new Error(`Aborted at step ${step.index} due to payment failure.`);
+				} else throw new Error(`Payment required for step ${step.index} but no interactive terminal available. Configure wallet with \`chain-insights config set walletPrivateKey <key>\`. Aborting.`);
+				else {
+					const completedMsg = step.index - 1 - startIndex > 0 ? `Completed: steps ${startIndex + 1}..${step.index - 1}.` : "No steps completed before failure.";
+					console.error(`Step ${step.index} failed: ${err.message}. ${completedMsg} Run with --from ${step.index} to resume.`);
+					throw err;
+				}
+			}
+			await require_evidence.EvidenceStore.append(caseId, {
+				source: step.tool,
+				content: result,
+				queryParams: JSON.stringify(step.params)
+			});
+			evidenceCount++;
+			console.log(`  (${result.length} chars stored)`);
+		}
+		if (playbook.name === "trace-funds") try {
+			const viz = await require_viz.generateVisualization({ caseId });
+			console.log(`Visualization generated: ${viz.htmlPath}`);
+		} catch {
+			console.log("No transaction data to visualize.");
+		}
+		console.log(`Playbook complete. Case: ${caseId}. Evidence: ${evidenceCount} entries.`);
+	} finally {
+		await client.close();
+	}
+} };
+//#endregion
+exports.PlaybookRunner = PlaybookRunner;