blun-king-cli 9.1.587 → 9.1.588

package/standard-skills/blun-session-inspector/scripts/inspect-session.cjs

@@ -1,437 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const readline = require('node:readline');
-
-function fail(code, details) {
-  process.stderr.write(`${JSON.stringify({ error: code, ...details })}\n`);
-  process.exitCode = 1;
-}
-
-function parseArgs(argv) {
-  const options = {
-    blunHome: process.env.BLUN_HOME || path.join(os.homedir(), '.blun'),
-    profile: 'default',
-    list: null,
-    includeMetadata: false,
-    selector: null,
-  };
-
-  for (let index = 0; index < argv.length; index += 1) {
-    const argument = argv[index];
-    if (argument === '--blun-home') {
-      options.blunHome = argv[index += 1];
-    } else if (argument === '--profile') {
-      options.profile = argv[index += 1];
-    } else if (argument === '--list') {
-      const raw = argv[index + 1];
-      if (raw && !raw.startsWith('--')) index += 1;
-      options.list = raw && !raw.startsWith('--') ? Number(raw) : 20;
-    } else if (argument === '--include-metadata') {
-      options.includeMetadata = true;
-    } else if (argument.startsWith('--')) {
-      throw new Error(`unknown_option:${argument}`);
-    } else if (options.selector === null) {
-      options.selector = argument;
-    } else {
-      throw new Error('too_many_session_selectors');
-    }
-  }
-
-  if (!options.blunHome) throw new Error('missing_blun_home');
-  if (!/^[a-z0-9][a-z0-9_-]{0,31}$/u.test(options.profile)) throw new Error('invalid_profile');
-  if (options.list !== null && (!Number.isInteger(options.list) || options.list < 1 || options.list > 1000)) {
-    throw new Error('invalid_list_limit');
-  }
-  if (options.list === null && !options.selector) throw new Error('missing_session_selector');
-  return options;
-}
-
-async function readJsonLines(filePath, onRecord, onWarning) {
-  const input = fs.createReadStream(filePath, { encoding: 'utf8' });
-  const lines = readline.createInterface({ input, crlfDelay: Infinity });
-  let lineNumber = 0;
-  for await (const line of lines) {
-    lineNumber += 1;
-    if (!line.trim()) continue;
-    try {
-      const record = JSON.parse(line);
-      if (!record || typeof record !== 'object' || Array.isArray(record)) {
-        onWarning({ code: 'unsupported_record', line: lineNumber });
-        continue;
-      }
-      await onRecord(record, lineNumber);
-    } catch {
-      onWarning({ code: 'invalid_json', line: lineNumber });
-    }
-  }
-}
-
-async function loadSessionIndex(profileRoot) {
-  const indexPath = path.join(profileRoot, 'session_index.jsonl');
-  if (!fs.existsSync(indexPath)) throw new Error('session_index_not_found');
-  const sessions = new Map();
-  const warnings = [];
-  await readJsonLines(indexPath, (entry) => {
-    if (typeof entry.sessionId !== 'string' || typeof entry.sessionDir !== 'string') {
-      warnings.push({ scope: 'session_index', code: 'invalid_session_entry' });
-      return;
-    }
-    sessions.set(entry.sessionId, entry);
-  }, (warning) => warnings.push({ scope: 'session_index', ...warning }));
-  return { sessions: [...sessions.values()], warnings };
-}
-
-function sessionModifiedTime(sessionDir) {
-  try {
-    return fs.statSync(sessionDir).mtime.toISOString();
-  } catch {
-    return null;
-  }
-}
-
-function isPathInside(parent, candidate) {
-  const relative = path.relative(path.resolve(parent), path.resolve(candidate));
-  return relative !== ''
-    && relative !== '..'
-    && !relative.startsWith(`..${path.sep}`)
-    && !path.isAbsolute(relative);
-}
-
-function requireSafeSessionPath(profileRoot, sessionDir) {
-  if (!isPathInside(path.join(profileRoot, 'sessions'), sessionDir)) {
-    throw new Error('unsafe_session_path');
-  }
-}
-
-function agentWireFiles(sessionDir) {
-  const agentsDir = path.join(sessionDir, 'agents');
-  if (!fs.existsSync(agentsDir)) return [];
-  return fs.readdirSync(agentsDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => ({
-      agent: entry.name,
-      wirePath: path.join(agentsDir, entry.name, 'wire.jsonl'),
-    }))
-    .filter((entry) => fs.existsSync(entry.wirePath))
-    .sort((left, right) => left.agent.localeCompare(right.agent));
-}
-
-function emptyUsage() {
-  return {
-    records: 0,
-    input_other: 0,
-    input_cache_read: 0,
-    input_cache_creation: 0,
-    input_total: 0,
-    output: 0,
-  };
-}
-
-function emptyCompactions() {
-  return { begun: 0, applied: 0, completed: 0, cancelled: 0, compacted_records: 0 };
-}
-
-function numberValue(value) {
-  return Number.isFinite(Number(value)) ? Number(value) : 0;
-}
-
-function emptyTokenSeries() {
-  return { total: 0, min: null, max: null, last: null };
-}
-
-function addTokenValue(series, value) {
-  series.total += value;
-  series.min = series.min === null ? value : Math.min(series.min, value);
-  series.max = series.max === null ? value : Math.max(series.max, value);
-  series.last = value;
-}
-
-function usageValue(usage, camelName, snakeName) {
-  return numberValue(usage?.[camelName] ?? usage?.[snakeName]);
-}
-
-async function summarizeWire(agent, wirePath, warnings) {
-  const summary = {
-    agent,
-    records: 0,
-    first_time: null,
-    last_time: null,
-    turn_prompts: 0,
-    turn_steers: 0,
-    turn_cancellations: 0,
-    messages: 0,
-    loop_events: 0,
-    provider_steps_started: 0,
-    provider_steps_finished: 0,
-    tool_calls: 0,
-    tool_results: 0,
-    top_tools: [],
-    usage: emptyUsage(),
-    full_compactions: emptyCompactions(),
-  };
-  const toolCounts = new Map();
-
-  await readJsonLines(wirePath, (record) => {
-    summary.records += 1;
-    const time = numberValue(record.time ?? record.created_at);
-    if (time > 0) {
-      summary.first_time = summary.first_time === null ? time : Math.min(summary.first_time, time);
-      summary.last_time = summary.last_time === null ? time : Math.max(summary.last_time, time);
-    }
-
-    if (record.type === 'turn.prompt') summary.turn_prompts += 1;
-    else if (record.type === 'turn.steer') summary.turn_steers += 1;
-    else if (record.type === 'turn.cancel') summary.turn_cancellations += 1;
-    else if (record.type === 'context.append_message') summary.messages += 1;
-    else if (record.type === 'context.append_loop_event') {
-      summary.loop_events += 1;
-      if (record.event?.type === 'step.begin') summary.provider_steps_started += 1;
-      else if (record.event?.type === 'step.end') summary.provider_steps_finished += 1;
-      else if (record.event?.type === 'tool.call') {
-        summary.tool_calls += 1;
-        const name = typeof record.event.name === 'string' && record.event.name ? record.event.name : '<unknown>';
-        toolCounts.set(name, (toolCounts.get(name) || 0) + 1);
-      } else if (record.event?.type === 'tool.result') summary.tool_results += 1;
-    } else if (record.type === 'usage.record') {
-      const usage = record.usage || {};
-      const inputOther = usageValue(usage, 'inputOther', 'input_other');
-      const inputCacheRead = usageValue(usage, 'inputCacheRead', 'input_cache_read');
-      const inputCacheCreation = usageValue(usage, 'inputCacheCreation', 'input_cache_creation');
-      summary.usage.records += 1;
-      summary.usage.input_other += inputOther;
-      summary.usage.input_cache_read += inputCacheRead;
-      summary.usage.input_cache_creation += inputCacheCreation;
-      summary.usage.input_total += inputOther + inputCacheRead + inputCacheCreation;
-      summary.usage.output += usageValue(usage, 'output', 'output_tokens');
-    } else if (record.type === 'full_compaction.begin') summary.full_compactions.begun += 1;
-    else if (record.type === 'context.apply_compaction') {
-      summary.full_compactions.applied += 1;
-      summary.full_compactions.compacted_records += numberValue(record.compactedCount ?? record.compacted_count);
-    } else if (record.type === 'full_compaction.complete') summary.full_compactions.completed += 1;
-    else if (record.type === 'full_compaction.cancel') summary.full_compactions.cancelled += 1;
-  }, (warning) => warnings.push({ scope: 'wire', agent, ...warning }));
-
-  summary.top_tools = [...toolCounts.entries()]
-    .map(([name, calls]) => ({ name, calls }))
-    .sort((left, right) => right.calls - left.calls || left.name.localeCompare(right.name));
-  return summary;
-}
-
-function addUsage(target, source) {
-  for (const key of Object.keys(target)) target[key] += source[key];
-}
-
-function addCompactions(target, source) {
-  for (const key of Object.keys(target)) target[key] += source[key];
-}
-
-function combineAgents(agents) {
-  const totals = {
-    records: 0,
-    turn_prompts: 0,
-    turn_steers: 0,
-    turn_cancellations: 0,
-    messages: 0,
-    loop_events: 0,
-    provider_steps_started: 0,
-    provider_steps_finished: 0,
-    tool_calls: 0,
-    tool_results: 0,
-    top_tools: [],
-    usage: emptyUsage(),
-    full_compactions: emptyCompactions(),
-  };
-  const toolCounts = new Map();
-  const numericKeys = [
-    'records',
-    'turn_prompts',
-    'turn_steers',
-    'turn_cancellations',
-    'messages',
-    'loop_events',
-    'provider_steps_started',
-    'provider_steps_finished',
-    'tool_calls',
-    'tool_results',
-  ];
-
-  for (const agent of agents) {
-    for (const key of numericKeys) totals[key] += agent[key];
-    addUsage(totals.usage, agent.usage);
-    addCompactions(totals.full_compactions, agent.full_compactions);
-    for (const tool of agent.top_tools) toolCounts.set(tool.name, (toolCounts.get(tool.name) || 0) + tool.calls);
-  }
-  totals.top_tools = [...toolCounts.entries()]
-    .map(([name, calls]) => ({ name, calls }))
-    .sort((left, right) => right.calls - left.calls || left.name.localeCompare(right.name));
-  return totals;
-}
-
-async function summarizeTelemetry(telemetryDir, sessionId, warnings) {
-  const summary = {
-    micro_compactions: 0,
-    full_compaction_failures: 0,
-    offloaded_tool_results: 0,
-    offloaded_output_chars: 0,
-    truncated_tool_results: 0,
-    truncated_tool_arguments: 0,
-    truncated_tool_argument_tokens_saved: 0,
-  };
-  if (!fs.existsSync(telemetryDir)) return summary;
-
-  const files = fs.readdirSync(telemetryDir, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith('.jsonl'))
-    .map((entry) => ({ name: entry.name, filePath: path.join(telemetryDir, entry.name) }));
-  for (const file of files) {
-    await readJsonLines(file.filePath, (record) => {
-      if (record.session_id !== sessionId) return;
-      if (record.event === 'micro_compaction_finished') {
-        summary.micro_compactions += 1;
-        summary.truncated_tool_results += numberValue(record.properties?.truncated_tool_result_count);
-        summary.truncated_tool_arguments += numberValue(record.properties?.truncated_tool_argument_count);
-        summary.truncated_tool_argument_tokens_saved += Math.max(0,
-          numberValue(record.properties?.truncated_tool_argument_tokens_before)
-            - numberValue(record.properties?.truncated_tool_argument_tokens_after));
-      } else if (record.event === 'compaction_failed') {
-        summary.full_compaction_failures += 1;
-      } else if (record.event === 'tool_result_offloaded') {
-        summary.offloaded_tool_results += 1;
-        summary.offloaded_output_chars += numberValue(record.properties?.output_size_chars);
-      }
-    }, (warning) => warnings.push({ scope: 'telemetry', file: file.name, ...warning }));
-  }
-  return summary;
-}
-
-async function summarizeToolSchemas(logPath) {
-  const summary = {
-    requests: 0,
-    deferred_requests: 0,
-    suppression_reasons: [],
-    eligible_schema_tokens: emptyTokenSeries(),
-    selected_schema_tokens: emptyTokenSeries(),
-    estimated_schema_tokens_avoided: 0,
-    last: null,
-  };
-  if (!fs.existsSync(logPath)) return summary;
-
-  const reasonCounts = new Map();
-  const input = fs.createReadStream(logPath, { encoding: 'utf8' });
-  const lines = readline.createInterface({ input, crlfDelay: Infinity });
-  for await (const line of lines) {
-    if (!line.includes('turn request tools')) continue;
-    const values = Object.fromEntries(
-      [...line.matchAll(/\b(toolSuppressionReason|eligibleToolCount|selectedToolCount|deferredToolCount|eligibleToolSchemaTokens|selectedToolSchemaTokens)=([^\s]+)/gu)]
-        .map((match) => [match[1], match[2]]),
-    );
-    const numericKeys = [
-      'eligibleToolCount',
-      'selectedToolCount',
-      'deferredToolCount',
-      'eligibleToolSchemaTokens',
-      'selectedToolSchemaTokens',
-    ];
-    if (!values.toolSuppressionReason || !numericKeys.every((key) => /^\d+$/u.test(values[key] || ''))) continue;
-
-    const eligibleToolCount = Number(values.eligibleToolCount);
-    const selectedToolCount = Number(values.selectedToolCount);
-    const deferredToolCount = Number(values.deferredToolCount);
-    const eligibleSchemaTokens = Number(values.eligibleToolSchemaTokens);
-    const selectedSchemaTokens = Number(values.selectedToolSchemaTokens);
-    summary.requests += 1;
-    if (deferredToolCount > 0) summary.deferred_requests += 1;
-    reasonCounts.set(values.toolSuppressionReason, (reasonCounts.get(values.toolSuppressionReason) || 0) + 1);
-    addTokenValue(summary.eligible_schema_tokens, eligibleSchemaTokens);
-    addTokenValue(summary.selected_schema_tokens, selectedSchemaTokens);
-    summary.estimated_schema_tokens_avoided += Math.max(0, eligibleSchemaTokens - selectedSchemaTokens);
-    summary.last = {
-      eligible_tool_count: eligibleToolCount,
-      selected_tool_count: selectedToolCount,
-      deferred_tool_count: deferredToolCount,
-      eligible_schema_tokens: eligibleSchemaTokens,
-      selected_schema_tokens: selectedSchemaTokens,
-    };
-  }
-  summary.suppression_reasons = [...reasonCounts.entries()]
-    .map(([reason, requests]) => ({ reason, requests }))
-    .sort((left, right) => right.requests - left.requests || left.reason.localeCompare(right.reason));
-  return summary;
-}
-
-function listSessions(options, profileRoot, sessions, warnings) {
-  const listed = sessions
-    .filter((entry) => {
-      try {
-        requireSafeSessionPath(profileRoot, entry.sessionDir);
-        return true;
-      } catch {
-        warnings.push({ scope: 'session_index', code: 'unsafe_session_path', session_id: entry.sessionId });
-        return false;
-      }
-    })
-    .map((entry) => {
-      const item = {
-        session_id: entry.sessionId,
-        agents: agentWireFiles(entry.sessionDir).length,
-        last_modified: sessionModifiedTime(entry.sessionDir),
-      };
-      if (options.includeMetadata) {
-        item.session_dir = entry.sessionDir;
-        item.work_dir = entry.workDir || null;
-      }
-      return item;
-    })
-    .sort((left, right) => String(right.last_modified).localeCompare(String(left.last_modified)))
-    .slice(0, options.list);
-  return { mode: 'list', profile: options.profile, sessions: listed, warnings };
-}
-
-async function inspectSession(options, profileRoot, sessions, inheritedWarnings) {
-  const matches = sessions.filter((entry) => entry.sessionId === options.selector || entry.sessionId.startsWith(options.selector));
-  if (matches.length === 0) throw new Error('session_not_found');
-  if (matches.length > 1) throw new Error('ambiguous_session_prefix');
-  const entry = matches[0];
-  requireSafeSessionPath(profileRoot, entry.sessionDir);
-  const warnings = [...inheritedWarnings];
-  const wires = agentWireFiles(entry.sessionDir);
-  if (wires.length === 0) warnings.push({ scope: 'session', code: 'wire_not_found' });
-  const agents = [];
-  for (const wire of wires) agents.push(await summarizeWire(wire.agent, wire.wirePath, warnings));
-
-  const result = {
-    mode: 'summary',
-    profile: options.profile,
-    session_id: entry.sessionId,
-    agents,
-    totals: combineAgents(agents),
-    telemetry: await summarizeTelemetry(path.join(options.blunHome, 'telemetry'), entry.sessionId, warnings),
-    tool_schemas: await summarizeToolSchemas(path.join(entry.sessionDir, 'logs', 'blun.log')),
-    warnings,
-  };
-  if (options.includeMetadata) {
-    result.session_dir = entry.sessionDir;
-    result.work_dir = entry.workDir || null;
-  }
-  return result;
-}
-
-async function main() {
-  let options;
-  try {
-    options = parseArgs(process.argv.slice(2));
-    const profileRoot = path.join(options.blunHome, 'profile', options.profile);
-    const { sessions, warnings } = await loadSessionIndex(profileRoot);
-    const result = options.list !== null
-      ? listSessions(options, profileRoot, sessions, warnings)
-      : await inspectSession(options, profileRoot, sessions, warnings);
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-  } catch (error) {
-    fail(String(error?.message || error), options?.selector ? { selector: options.selector } : {});
-  }
-}
-
-void main();