blun-king-cli 9.1.80 → 9.1.81

package/LIESMICH.txt

@@ -9,7 +9,7 @@ Installation
 ------------
 Die geprüfte Version exakt global installieren:
 
-  npm install -g blun-king-cli@9.1.80
+  npm install -g blun-king-cli@9.1.81
 
 Start
 -----
@@ -94,6 +94,18 @@ Das Telemetrieereignis `tool_result_offloaded` enthält ausschließlich `tool_na
 
 Reguläre `Agent`-Teilaufgaben verwenden eine eigene `ContextMemory` und eine eigene `wire.jsonl` in einem getrennten Agentenverzeichnis. Der Hauptagent erhält nur die Ergebniszusammenfassung, sodass lange Teilaufgaben nicht den Hauptverlauf füllen. `TodoList` speichert Pläne weiterhin maschinenlesbar im Sitzungs-Wire; `blun handoff` übergibt sie zusammen mit prüfbaren Hashes zwischen CLI, Desktop und Web.
 
+Rein lesende Sitzungsdiagnose
+--------------------------------
+
+Der mitgelieferte Standardskill `blun-session-inspector` untersucht den nur ergänzten Sitzungs-Wire und die zugehörigen Telemetriedateien, ohne eine Sitzung zu verändern. Er meldet Modellschritte, Werkzeugaufrufe, Zähler zum Tokenverbrauch, Voll- und Mikroverdichtungen, fehlgeschlagene Verdichtungen sowie ausgelagerte Werkzeugergebnisse. Prompts, Systemanweisungen, Werkzeugargumente, Werkzeugergebnisse, private Pfade und verborgenes Denken erscheinen nicht in der Standardausgabe.
+
+Beispiele:
+
+  node "$SKILL_DIR/scripts/inspect-session.cjs" --list 20
+  node "$SKILL_DIR/scripts/inspect-session.cjs" SESSION_ID
+
+Ein eindeutiger Präfix der Sitzungs-ID genügt. `--profile NAME` wählt ein anderes Profil. `--include-metadata` zeigt zusätzlich Arbeits- und Sitzungsverzeichnis und sollte nur verwendet werden, wenn diese Pfade wirklich gebraucht werden. Der Inspektor setzt eine Sitzung niemals fort, lädt sie nicht neu, verdichtet sie nicht und löscht sie nicht.
+
 Zug-Wächter
 -----------
 Läuft ein Zug 20 Minuten ohne neues Werkzeugergebnis, meldet die Konsole den

package/README.md

@@ -9,7 +9,7 @@ Voraussetzung ist Node.js 24.15 oder neuer. Die geprüfte Version wird exakt
 installiert:
 
 ```powershell
-npm install -g blun-king-cli@9.1.80
+npm install -g blun-king-cli@9.1.81
 ```
 
 ## Reproduzierbares Staging und Packen
@@ -116,6 +116,19 @@ Das Telemetrieereignis `tool_result_offloaded` enthält ausschließlich `tool_na
 
 Reguläre `Agent`-Teilaufgaben verwenden eine eigene `ContextMemory` und eine eigene `wire.jsonl` in einem getrennten Agentenverzeichnis. Der Hauptagent erhält nur die Ergebniszusammenfassung, sodass lange Teilaufgaben nicht den Hauptverlauf füllen. `TodoList` speichert Pläne weiterhin maschinenlesbar im Sitzungs-Wire; `blun handoff` übergibt sie zusammen mit prüfbaren Hashes zwischen CLI, Desktop und Web.
 
+## Rein lesende Sitzungsdiagnose
+
+Der mitgelieferte Standardskill `blun-session-inspector` untersucht den nur ergänzten Sitzungs-Wire und die zugehörigen Telemetriedateien, ohne eine Sitzung zu verändern. Er meldet Modellschritte, Werkzeugaufrufe, Zähler zum Tokenverbrauch, Voll- und Mikroverdichtungen, fehlgeschlagene Verdichtungen sowie ausgelagerte Werkzeugergebnisse. Prompts, Systemanweisungen, Werkzeugargumente, Werkzeugergebnisse, private Pfade und verborgenes Denken erscheinen nicht in der Standardausgabe.
+
+Beispiele:
+
+```text
+node "$SKILL_DIR/scripts/inspect-session.cjs" --list 20
+node "$SKILL_DIR/scripts/inspect-session.cjs" SESSION_ID
+```
+
+Ein eindeutiger Präfix der Sitzungs-ID genügt. `--profile NAME` wählt ein anderes Profil. `--include-metadata` zeigt zusätzlich Arbeits- und Sitzungsverzeichnis und sollte nur verwendet werden, wenn diese Pfade wirklich gebraucht werden. Der Inspektor setzt eine Sitzung niemals fort, lädt sie nicht neu, verdichtet sie nicht und löscht sie nicht.
+
 ## Zug-Wächter
 
 Läuft ein Zug 20 Minuten ohne neues Werkzeugergebnis, meldet die Konsole den

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blun-king-cli",
-  "version": "9.1.80",
+  "version": "9.1.81",
   "description": "BLUN CLI - your own AI agent with a Telegram channel. Get it done. With BLUN.",
   "license": "MIT",
   "bin": {

package/standard-skills/blun-session-inspector/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: blun-session-inspector
+description: Inspect local BLUN Code session health read-only. Use when asked about compactions, token usage, tool-call volume, offloaded tool results, provider steps, or a session that appears slow or stuck.
+license: MIT
+compatibility: designed for BLUN Code
+---
+
+# BLUN Session Inspector
+
+Use the bundled script instead of manually reading `wire.jsonl` or telemetry files. It reports counts and timing metadata without returning prompts, system instructions, tool arguments, tool results, private paths, or hidden reasoning.
+
+Resolve `SKILL_DIR` to the directory containing this file. Do not assume a user-specific installation path.
+
+List recent sessions:
+
+```bash
+node "$SKILL_DIR/scripts/inspect-session.cjs" --list 20
+```
+
+Inspect one session by full ID or unique prefix:
+
+```bash
+node "$SKILL_DIR/scripts/inspect-session.cjs" SESSION_ID
+```
+
+Use another profile or app home only when needed:
+
+```bash
+node "$SKILL_DIR/scripts/inspect-session.cjs" SESSION_ID --profile PROFILE
+node "$SKILL_DIR/scripts/inspect-session.cjs" SESSION_ID --blun-home PATH
+```
+
+Add `--include-metadata` only when the work directory and session directory are relevant. Summarize the JSON instead of pasting it verbatim. Distinguish stored counts from your interpretation, mention warnings, and do not claim that telemetry covers periods before an event was introduced.
+
+Keep inspection read-only. Never edit, delete, compact, resume, reload, or restart a session as part of diagnosis.
+
+This skill adopts the read-only, smallest-useful-view approach from the MIT-licensed Deep Agents Thread Inspector while using BLUN Code's append-only wire and telemetry formats.
+
+Source: https://github.com/langchain-ai/deepagents/tree/main/libs/code/deepagents_code/built_in_skills/deepagents-thread-inspector

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

@@ -0,0 +1,364 @@
+#!/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 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,
+  };
+  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);
+      } 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;
+}
+
+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),
+    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();