brainiac 0.0.33 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa14f181c9965192fcc2507837be14e29cc9bce6a0273d806dd556eb2bfb72e2
-  data.tar.gz: c1d2fcbed4ce125a150d442e4cc3a1d68dfa856c424addf981904b4b88393b70
+  metadata.gz: 82f144b517fd0197684d1912858134c0a6b440263cf2e6bb43d1c4e2651aec3a
+  data.tar.gz: 415ae3b9fad9b4d407e13147ce0c28286b8292897175f45c37d39b4dfbf2cccd
 SHA512:
-  metadata.gz: beaf113fb5acf361c73df0da4d93dd65a7a7159397c0b1c559e4b84df9396376148a95a7e09824744ca1d272ef51c6008da334bc906a3bd6ce8d940d0568f43a
-  data.tar.gz: 5382b695151def7319fcadfbb51ae84f6f4401b43b9de92ecd51e5c17b20a8e05723cd9943dfba4229ca70a7097f317c70f44b973e9d815f9815ee994b8414c9
+  metadata.gz: 567146d407026c606a08a9c3d592059a43f195f9785318d3763ad368aab002d16153a2b442cf778a06513b231327552201f71b1d7bb2680036214f0cf842e5cc
+  data.tar.gz: a41c6857915e2e9493f45fa0d49755e4958d6c4de6175a7171d7e25a8013ac3b3f498a7ab1933021c09b0bf3a5768bd1542176d59a0e4ad680e186ce7af74545

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brainiac (0.0.33)
+    brainiac (0.1.0)
       puma (~> 7.2)
       rackup (~> 2.3)
       sinatra (~> 4.1)
@@ -11,22 +11,22 @@ GEM
   specs:
     ast (2.4.3)
     base64 (0.3.0)
-    json (2.19.9)
-    language_server-protocol (3.17.0.5)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
     minitest (5.27.0)
     mustermann (3.1.1)
     nio4r (2.7.5)
-    parallel (2.1.0)
-    parser (3.3.11.1)
+    parallel (2.2.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     prism (1.9.0)
     puma (7.2.1)
       nio4r (~> 2.0)
     racc (1.8.1)
-    rack (3.2.6)
+    rack (3.2.7)
     rack-protection (4.2.1)
       base64 (>= 0.1.0)
       logger (>= 1.6.0)
@@ -50,7 +50,7 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     rubocop-performance (1.26.1)
@@ -65,7 +65,7 @@ GEM
       rack-protection (= 4.2.1)
       rack-session (>= 2.0.0, < 3)
       tilt (~> 2.0)
-    tilt (2.7.0)
+    tilt (2.9.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
@@ -84,20 +84,20 @@ DEPENDENCIES
 CHECKSUMS
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
-  brainiac (0.0.33)
-  json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
-  language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
+  brainiac (0.1.0)
+  json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
+  language_server-protocol (3.17.0.6) sha256=5ef2c0c138f8267e1bc631d3328347d354f96724b0af22f2c79516120443b7f0
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   minitest (5.27.0) sha256=2d3b17f8a36fe7801c1adcffdbc38233b938eb0b4966e97a6739055a45fa77d5
   mustermann (3.1.1) sha256=4c6170c7234d5499c345562ba7c7dfe73e1754286dcc1abb053064d66a127198
   nio4r (2.7.5) sha256=6c90168e48fb5f8e768419c93abb94ba2b892a1d0602cb06eef16d8b7df1dca1
-  parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
-  parser (3.3.11.1) sha256=d17ace7aabe3e72c3cc94043714be27cc6f852f104d81aa284c2281aecc65d54
+  parallel (2.2.0) sha256=e1059c5fd7b649558a0aec38a769f06a42942bdb40503d005a59c352fe011cd8
+  parser (3.3.12.0) sha256=21a6d7f755d5a24dfbdc6e6b772e4e879a52e7631a88bc5a3a134606052c9828
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
   puma (7.2.1) sha256=d7bf0e9cabd532e0d401e142cd94e3ac531e993610e2d80e6fbf9c26961414b0
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
-  rack (3.2.6) sha256=5ed78e1f73b2e25679bec7d45ee2d4483cc4146eb1be0264fc4d94cb5ef212c2
+  rack (3.2.7) sha256=93e13e1c24f93556671d85d2d79fa228c3485815c50d7e2f265b5330c6528fb7
   rack-protection (4.2.1) sha256=cf6e2842df8c55f5e4d1a4be015e603e19e9bc3a7178bae58949ccbb58558bac
   rack-session (2.1.2) sha256=595434f8c0c3473ae7d7ac56ecda6cc6dfd9d37c0b2b5255330aa1576967ffe8
   rackup (2.3.1) sha256=6c79c26753778e90983761d677a48937ee3192b3ffef6bc963c0950f94688868
@@ -105,11 +105,11 @@ CHECKSUMS
   rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
   regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
   rubocop (1.88.0) sha256=e420ddf1662d0ef34bc8a2910ac4b396a7ddda0b51a708264405241734b08e0b
-  rubocop-ast (1.49.1) sha256=4412f3ee70f6fe4546cc489548e0f6fcf76cafcfa80fa03af67098ffed755035
+  rubocop-ast (1.50.0) sha256=b9ca88300da0803ee222ad20cdb30494c0a784eed06fdc35d254b06d662788db
   rubocop-performance (1.26.1) sha256=cd19b936ff196df85829d264b522fd4f98b6c89ad271fa52744a8c11b8f71834
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
   sinatra (4.2.1) sha256=b7aeb9b11d046b552972ade834f1f9be98b185fa8444480688e3627625377080
-  tilt (2.7.0) sha256=0d5b9ba69f6a36490c64b0eee9f6e9aad517e20dcc848800a06eb116f08c6ab3
+  tilt (2.9.0) sha256=da5735d0280bba96e9a91041bb14aee435ccad5c17b0fa519249ae543d9aa3a5
   unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
   unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
 

data/README.md

@@ -1270,6 +1270,32 @@ curl "http://localhost:4567/api/gif?q=excited"              # Search for GIFs (r
 curl http://localhost:4567/api/cron                         # Cron jobs and thread status
 curl http://localhost:4567/api/logs                         # Read log files
 curl http://localhost:4567/api/status                       # Active agent sessions (used by monitor)
+curl "http://localhost:4567/api/sessions/history?limit=25"  # Durable session history (survives restarts)
+```
+
+### Session History
+
+`/api/status` returns only *live* sessions plus the last 10 finished ones held in memory
+(wiped on every restart). For durable, restart-surviving history use
+`GET /api/sessions/history?limit=N`, backed by an append-only JSONL log at
+`~/.brainiac/session-history.jsonl`.
+
+Every finished agent session is recorded with timing, identity (agent, CLI, model, source),
+exit status, and — where the provider exposes it — **session heaviness**: context window
+usage and credits spent. Heaviness is captured at completion time via a provider-specific
+probe that is **declared in the provider config**, not hardcoded in brainiac. Add a
+`heaviness_probe` block to `~/.brainiac/cli-providers/<name>.json`:
+
+```json
+"heaviness_probe": { "type": "kiro_sqlite", "db_path": "~/.local/share/kiro-cli/data.sqlite3" }
+```
+
+`type` selects the probe strategy and `db_path` points at the provider's local usage store,
+so enabling/disabling a provider or moving its data store is pure JSON. kiro-cli ships with a
+`kiro_sqlite` probe (reads its local conversation sqlite, read-only). A genuinely new storage
+mechanism needs a small probe implementation in `lib/brainiac/session_history.rb`; providers
+with no `heaviness_probe` simply record timing + identity. The file is trimmed to the most
+recent 500 records.
 ```
 
 ## Development

data/lib/brainiac/helpers.rb

@@ -35,7 +35,7 @@ def load_cli_provider(provider_name)
   %w[prompt_flag list_models_command resume_flag resume_args resume_id_flag new_session_id_flag
      session_list_command session_id_field session_directory_field session_updated_field
      session_list_path session_dir output_last_message_flag cwd_flag config_override_flag
-     effort_config_key effort_map title_flag].each do |key|
+     effort_config_key effort_map title_flag heaviness_probe].each do |key|
     next unless raw[key]
     next if raw[key].respond_to?(:empty?) && raw[key].empty?
 
@@ -507,6 +507,74 @@ rescue StandardError => e
   nil
 end
 
+# Detect when an agent exited cleanly (exit 0) but produced no usable response.
+# This covers cases the crash path misses because the exit code is 0 — most notably a
+# CLI that prints a request/usage-limit notice and exits without doing any work.
+#
+# Returns a short human-readable reason string when the session yielded no response,
+# or nil when the session did produce output (i.e. nothing to surface).
+#
+# @param log_file [String, nil] Path to the agent's log file
+# @param output_content [String, nil] Structured output captured via --output-last-message, if any
+NO_OUTPUT_LIMIT_PATTERNS = [
+  /\bmonthly request limit reached\b/i,
+  /\brequest limit reached\b/i,
+  /\busage limit\b/i,
+  /\brate limit(?:ed|ing)?\b/i,
+  /\bquota (?:exceeded|reached)\b/i,
+  /\btoo many requests\b/i
+].freeze
+
+def detect_no_output_reason(log_file, output_content)
+  # If we captured a structured response, the session clearly produced output.
+  return nil if output_content && !output_content.strip.empty?
+
+  tail = extract_crash_snippet(log_file, max_lines: 40)
+  return nil if tail.nil?
+
+  limit_line = tail.lines.map(&:strip).reverse.find do |line|
+    NO_OUTPUT_LIMIT_PATTERNS.any? { |re| line.match?(re) }
+  end
+  return "hit a request/usage limit: #{limit_line}" if limit_line
+
+  # No structured output and no recognizable limit notice. Treat a log that carries no
+  # assistant text as "produced no response" so the channel isn't left silent. We can't
+  # parse every CLI's transcript here, so this is best-effort: only flag when the log is
+  # effectively empty of content beyond startup/boilerplate lines.
+  meaningful = tail.lines.map(&:strip).reject do |line|
+    line.empty? ||
+      line.start_with?("---", "▸") ||
+      line.match?(/all tools are now trusted/i) ||
+      line.match?(/mcp server did not load/i) ||
+      line.match?(/agents can sometimes do unexpected things/i) ||
+      line.match?(%r{learn more at https?://}i)
+  end
+  return "produced no response (log contained no agent output)" if meaningful.empty?
+
+  nil
+end
+
+# Surface a clean-exit-but-no-response session to the originating channel. Reuses the
+# crash notification delivery path (the :agent_crashed hook) so plugins deliver it the
+# same way they deliver failures, but frames it as "no response" rather than a crash.
+def notify_agent_no_output(reason:, log_file:, agent_name:, source:, source_context:, project_config:)
+  agent_display = agent_name || "Agent"
+  snippet = extract_crash_snippet(log_file)
+
+  handled = Brainiac.emit(:agent_crashed,
+                          exit_status: 0, log_file: log_file, agent_name: agent_display,
+                          source: source, source_context: source_context, project_config: project_config,
+                          snippet: snippet, no_output: true, no_output_reason: reason)
+
+  if handled.any?
+    LOG.info "[NoOutput] #{agent_display} #{reason} — notified via #{source}"
+  else
+    LOG.warn "[NoOutput] #{agent_display} #{reason} but no plugin handled notification (source: #{source})"
+  end
+rescue StandardError => e
+  LOG.error "[NoOutput] Unexpected error: #{e.message}"
+end
+
 # Notify the originating channel that an agent crashed.
 # source: :github, :discord, or plugin-registered sources
 # source_context: hash with channel-specific info needed to post the notification
@@ -737,8 +805,6 @@ def run_agent(prompt, project_config:, chdir: nil, log_name: "agent", model: nil
                                   prompt_file: prompt_file, resume: should_resume,
                                   output_file: output_file, chdir: chdir, title: work_item_id,
                                   new_session_id: minted_session_id)
-  prompt_mode = resolved["prompt_mode"] || "stdin"
-
   spawn_env = agent_env_for(agent_name).merge(env)
 
   log_agent_launch(resolved: resolved, chdir: chdir, log_file: log_file, prompt_file: prompt_file,
@@ -748,11 +814,9 @@ def run_agent(prompt, project_config:, chdir: nil, log_name: "agent", model: nil
   project_key_for_restart = PROJECTS.find { |_k, v| v == project_config }&.first
   head_before, status_before = capture_git_state(chdir) if project_key_for_restart == "brainiac"
 
-  pid = spawn(spawn_env, *cmd,
-              chdir: chdir,
-              **(prompt_mode == "stdin" ? { in: prompt_file } : {}),
-              out: [log_file, "w"],
-              err: %i[child out])
+  started_at = Time.now
+  stdin_redirect = (resolved["prompt_mode"] || "stdin") == "stdin" ? { in: prompt_file } : {}
+  pid = spawn(spawn_env, *cmd, chdir: chdir, **stdin_redirect, out: [log_file, "w"], err: %i[child out])
 
   spawn_completion_watcher(
     pid: pid, agent_cli: resolved["agent_cli"], agent_config_name: agent_config_name,
@@ -762,7 +826,7 @@ def run_agent(prompt, project_config:, chdir: nil, log_name: "agent", model: nil
     card_number: card_number, skip_column_move: skip_column_move,
     output_file: output_file, resolved: resolved, minted_session_id: minted_session_id,
     head_before: head_before, status_before: status_before,
-    project_key_for_restart: project_key_for_restart
+    project_key_for_restart: project_key_for_restart, model: model, started_at: started_at
   )
 
   LOG.info "#{resolved["agent_cli"]} started (pid: #{pid}, agent: #{agent_config_name || "default"}, " \
@@ -773,10 +837,15 @@ end
 
 # Spawn a background thread that waits for the agent process to finish and runs completion handling.
 def spawn_completion_watcher(**ctx)
-  Thread.new do
+  thread = Thread.new do
     Process.wait(ctx[:pid])
     handle_agent_completion(**ctx)
   end
+  # Without this, an unrescued exception anywhere in handle_agent_completion silently
+  # kills the thread and is never logged — which previously hid completion-path failures
+  # (e.g. a step raising before session history was archived).
+  thread.report_on_exception = true
+  thread
 end
 
 # Log the details of an agent launch (command, prompt/output files, injected env).
@@ -1056,13 +1125,60 @@ def handle_agent_completion(**ctx)
   # Clean up the output file after hook emission (content already captured above).
   FileUtils.rm_f(ctx[:output_file]) if ctx[:output_file]
 
-  run_qmd_update(ctx[:agent_config_name])
-  log_skill_candidate(ctx[:log_file])
+  run_post_completion_steps(ctx, exit_status: agent_exit_status, signaled: agent_signaled, output_content: output_content)
+end
 
-  brain_push(message: "#{ctx[:agent_config_name] || "agent"}: #{ctx[:log_name]}")
+# Independent, best-effort steps that run after the lifecycle hook. Each is isolated via
+# completion_step so a failure in one (e.g. a raising notify path) can't abort the rest —
+# notably session-history archival, which must always run regardless of earlier steps.
+def run_post_completion_steps(ctx, exit_status:, signaled:, output_content:)
+  # Clean exit (0) but no usable response — e.g. the CLI hit a request/usage limit and
+  # bailed without doing work. The crash path only fires on non-zero exits, so this would
+  # otherwise be silent. Surface it to the originating channel.
+  completion_step("notify_no_output") do
+    notify_no_output_if_needed(ctx, exit_status: exit_status, signaled: signaled, output_content: output_content)
+  end
+
+  # Durable session history — record every finished session to disk (survives restarts),
+  # including provider-specific "heaviness" (context window usage + credits). Best-effort.
+  completion_step("archive_session_history") do
+    archive_session_history(ctx: ctx, exit_status: exit_status, signaled: signaled)
+  end
+
+  completion_step("qmd_update") { run_qmd_update(ctx[:agent_config_name]) }
+  completion_step("skill_candidate") { log_skill_candidate(ctx[:log_file]) }
+  completion_step("brain_push") { brain_push(message: "#{ctx[:agent_config_name] || "agent"}: #{ctx[:log_name]}") }
   # check_brainiac_restart(ctx[:head_before], ctx[:status_before], ctx[:chdir], ctx[:project_key_for_restart], ctx[:agent_config_name])
 end
 
+# Run an independent post-completion step, logging and swallowing any failure so one
+# broken step (e.g. a plugin-facing call raising) can't abort the remaining steps —
+# notably session-history archival, which must not depend on earlier steps succeeding.
+def completion_step(name)
+  yield
+rescue StandardError => e
+  LOG.error "[Completion] step '#{name}' failed: #{e.class}: #{e.message}"
+  LOG.error "[Completion]   #{e.backtrace.first(3).join("\n  ")}" if e.backtrace
+  nil
+end
+
+# Surface a clean-exit session that produced no response, pulling fields from the
+# completion context. Only fires for exit 0 (non-zero already goes through the crash
+# path) with a source to notify. Extracted from handle_agent_completion.
+def notify_no_output_if_needed(ctx, exit_status:, signaled:, output_content:)
+  return unless ctx[:source]
+  return if signaled
+  return unless exit_status&.zero?
+
+  reason = detect_no_output_reason(ctx[:log_file], output_content)
+  return unless reason
+
+  notify_agent_no_output(
+    reason: reason, log_file: ctx[:log_file], agent_name: ctx[:agent_name],
+    source: ctx[:source], source_context: ctx[:source_context], project_config: ctx[:project_config]
+  )
+end
+
 # Capture the CLI session id after a run, if the provider and working dir are known.
 def capture_session_id_if_possible(ctx)
   return unless ctx[:resolved] && ctx[:chdir]

data/lib/brainiac/routes/api.rb

@@ -265,6 +265,13 @@ get "/api/status" do
   end
 end
 
+get "/api/sessions/history" do
+  content_type :json
+  limit = (params["limit"] || 50).to_i.clamp(1, SESSION_HISTORY_MAX)
+  history = read_session_history(limit: limit)
+  { history: history, count: history.size }.to_json
+end
+
 post "/api/sessions/kill/:card_key" do
   content_type :json
   card_key = params[:card_key]

data/lib/brainiac/session_history.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+# Durable session history + "session heaviness" tracking.
+#
+# The in-memory RECENT_SESSIONS (see sessions.rb) only holds the last 10 finished
+# sessions and is wiped on every brainiac restart. This module persists a durable,
+# append-only record of every completed agent session to disk so the monitor (and
+# anything else) can review real history: how long a session ran, which CLI/model it
+# used, where it came from, and — where the provider exposes it — how "heavy" the
+# session was (context window usage + credits spent).
+#
+# Storage: append-only JSONL at ~/.brainiac/session-history.jsonl (one record per line).
+# JSONL is chosen deliberately: appends are atomic-ish and cheap, the file survives
+# restarts, it's trivially tailable, and a corrupt line never poisons the whole file.
+# The file is trimmed to SESSION_HISTORY_MAX records to bound growth.
+
+SESSION_HISTORY_FILE = File.join(BRAINIAC_DIR, "session-history.jsonl")
+SESSION_HISTORY_MAX = 500
+SESSION_HISTORY_MUTEX = Mutex.new
+
+# Append a completed-session record to the durable history file.
+# `record` is a plain Hash; symbol keys are fine (serialized to JSON).
+# Best-effort: any failure is logged and swallowed — history is never allowed to
+# break the completion path.
+def record_session_history(record)
+  SESSION_HISTORY_MUTEX.synchronize do
+    FileUtils.mkdir_p(File.dirname(SESSION_HISTORY_FILE))
+    File.open(SESSION_HISTORY_FILE, "a") { |f| f.puts(JSON.generate(record)) }
+    trim_session_history!
+  end
+  LOG.info "[SessionHistory] Recorded session for #{record["agent"] || "?"} → #{SESSION_HISTORY_FILE}"
+  true
+rescue StandardError => e
+  LOG.warn "[SessionHistory] Failed to record session: #{e.class}: #{e.message}"
+  false
+end
+
+# Read the most recent `limit` session records, newest first.
+def read_session_history(limit: 50)
+  return [] unless File.exist?(SESSION_HISTORY_FILE)
+
+  lines = SESSION_HISTORY_MUTEX.synchronize { File.readlines(SESSION_HISTORY_FILE) }
+  records = lines.filter_map do |line|
+    line = line.strip
+    next if line.empty?
+
+    begin
+      JSON.parse(line)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+  records.last(limit).reverse
+rescue StandardError => e
+  LOG.warn "[SessionHistory] Failed to read history: #{e.message}"
+  []
+end
+
+# Keep the history file bounded. Call inside SESSION_HISTORY_MUTEX.
+def trim_session_history!
+  lines = File.readlines(SESSION_HISTORY_FILE)
+  return if lines.size <= SESSION_HISTORY_MAX
+
+  File.write(SESSION_HISTORY_FILE, lines.last(SESSION_HISTORY_MAX).join)
+rescue StandardError => e
+  LOG.warn "[SessionHistory] Failed to trim history: #{e.message}"
+end
+
+# Build the durable history record for a finished session and append it.
+# Called from handle_agent_completion. Gathers timing, identity, and — via the
+# provider-specific heaviness probe — context/credit usage. Never raises.
+def archive_session_history(ctx:, exit_status:, signaled:)
+  started_at = ctx[:started_at]
+  finished_at = Time.now
+  heaviness = session_heaviness(resolved: ctx[:resolved], chdir: ctx[:chdir])
+  source_context = ctx[:source_context] || {}
+  card_key = ctx[:card_key] || source_context[:card_key]
+  channel_id = ctx[:channel_id] || source_context[:channel_id]
+
+  record = {
+    "recorded_at" => finished_at.utc.iso8601,
+    "agent" => ctx[:agent_name] || ctx[:agent_config_name] || "Unknown",
+    "card_key" => card_key,
+    "card_number" => ctx[:card_number] || source_context[:card_number],
+    "source" => ctx[:source]&.to_s,
+    "channel_id" => channel_id,
+    "log_file" => ctx[:log_file],
+    "cli" => ctx[:agent_cli],
+    "model" => ctx[:model],
+    "started_at" => started_at&.utc&.iso8601,
+    "finished_at" => finished_at.utc.iso8601,
+    "duration_seconds" => started_at ? (finished_at - started_at).to_i : nil,
+    "exit_status" => exit_status,
+    "signaled" => signaled
+  }
+  record.merge!(heaviness) if heaviness
+  record.compact!
+
+  record_session_history(record)
+end
+
+# --- Provider-generic session heaviness probe ---
+#
+# "How heavy was this session?" — context window usage + credits spent.
+# This is inherently provider-specific: each CLI stores (or doesn't store) usage
+# differently. Rather than hardcode any one CLI in this file, brainiac reads a
+# `heaviness_probe` block from the provider's cli-providers/<name>.json. That config
+# declares WHICH probe strategy to use and WHERE its data lives, e.g.:
+#
+#   "heaviness_probe": { "type": "kiro_sqlite", "db_path": "~/.local/share/kiro-cli/data.sqlite3" }
+#
+# The config controls the "what and where" (enable/disable a provider, point it at a
+# moved db) with zero code changes. The "how" for each probe TYPE lives here in Ruby —
+# a genuinely new storage mechanism (a provider that logs usage to JSON, an HTTP
+# endpoint, etc.) still needs a small probe implementation, but pointing kiro at a new
+# path or turning a provider's probe on/off is pure JSON.
+#
+# Providers with no `heaviness_probe` (or an unknown type) simply yield nil and the
+# history record carries timing/identity only.
+#
+# Returns a Hash of string-keyed heaviness fields, or nil if unavailable:
+#   context_window_tokens, context_usage_pct, context_used_tokens, credits_used
+def session_heaviness(resolved:, chdir:)
+  return nil unless resolved && chdir
+
+  probe = resolved["heaviness_probe"]
+  return nil unless probe.is_a?(Hash)
+
+  case probe["type"]
+  when "kiro_sqlite"
+    kiro_session_heaviness(chdir, db_path: probe["db_path"])
+  end
+rescue StandardError => e
+  LOG.warn "[SessionHistory] Heaviness probe failed for #{chdir}: #{e.message}"
+  nil
+end
+
+# kiro-cli persists every conversation in a local sqlite keyed by working directory.
+# Each conversation's JSON carries the model's context window, the latest request's
+# context-usage percentage, and per-request credit usage. We read it read-only via the
+# sqlite3 CLI (no gem dependency) and derive the heaviness fields. Best-effort: any
+# problem (missing db, no row for this cwd, malformed json) yields nil.
+#
+# The db location comes from the provider's heaviness_probe.db_path so it's not baked
+# into brainiac; KIRO_DEFAULT_DB_PATH is only the fallback.
+KIRO_DEFAULT_DB_PATH = File.join(Dir.home, ".local", "share", "kiro-cli", "data.sqlite3")
+
+def kiro_session_heaviness(chdir, db_path: nil)
+  db = File.expand_path(db_path || KIRO_DEFAULT_DB_PATH)
+  return nil unless File.exist?(db)
+
+  key = File.expand_path(chdir)
+  # The CTE picks the most recently updated conversation for this working directory,
+  # then we pull the model's context window, the latest request's context-usage %, and
+  # the summed credit spend. `.timeout` (via -cmd, so it doesn't emit output) keeps us
+  # from hanging if kiro-cli is mid-write.
+  sql = <<~SQL.gsub(/\s+/, " ").strip
+    WITH latest AS (
+      SELECT value FROM conversations_v2
+      WHERE key = #{sqlite_quote(key)} ORDER BY updated_at DESC LIMIT 1
+    )
+    SELECT
+      json_extract(value, '$.model_info.context_window_tokens'),
+      (SELECT r.value ->> 'context_usage_percentage'
+         FROM latest, json_each(json_extract(latest.value, '$.user_turn_metadata.requests')) r
+         ORDER BY CAST(r.key AS INTEGER) DESC LIMIT 1),
+      (SELECT ROUND(SUM(CAST(u.value ->> 'value' AS REAL)), 4)
+         FROM latest, json_each(json_extract(latest.value, '$.user_turn_metadata.usage_info')) u
+         WHERE (u.value ->> 'unit') = 'credit')
+    FROM latest;
+  SQL
+
+  out = ""
+  status = nil
+  Timeout.timeout(6) do
+    out, status = Open3.capture2(
+      "sqlite3", "-separator", "\t", "-cmd", ".timeout 3000",
+      "file:#{db}?mode=ro", sql
+    )
+  end
+  return nil unless status&.success?
+
+  row = out.strip
+  return nil if row.empty?
+
+  window, pct, credits = row.split("\t", 3)
+  window = window.to_i
+  return nil if window.zero?
+
+  pct = pct.to_f
+  fields = { "context_window_tokens" => window, "context_usage_pct" => pct.round(2) }
+  fields["context_used_tokens"] = (window * pct / 100.0).round if pct.positive?
+  fields["credits_used"] = credits.to_f.round(4) if credits && !credits.empty?
+  fields
+end
+
+# Single-quote a string for safe literal interpolation into SQLite SQL.
+def sqlite_quote(str)
+  "'#{str.to_s.gsub("'", "''")}'"
+end

data/lib/brainiac/version.rb

@@ -2,5 +2,5 @@
 
 module Brainiac
   # @return [String] the current gem version
-  VERSION = "0.0.33"
+  VERSION = "0.1.0"
 end

data/lib/brainiac.rb

@@ -5,6 +5,7 @@ require_relative "brainiac/agents"
 require_relative "brainiac/brain"
 require_relative "brainiac/skills"
 require_relative "brainiac/sessions"
+require_relative "brainiac/session_history"
 require_relative "brainiac/prompts"
 require_relative "brainiac/helpers"
 require_relative "brainiac/intent"

data/receiver.rb

@@ -19,6 +19,7 @@ require_relative "lib/brainiac/agents"
 require_relative "lib/brainiac/brain"
 require_relative "lib/brainiac/skills"
 require_relative "lib/brainiac/sessions"
+require_relative "lib/brainiac/session_history"
 require_relative "lib/brainiac/prompts"
 require_relative "lib/brainiac/helpers"
 require_relative "lib/brainiac/notifications"
@@ -100,6 +101,16 @@ configure do
 end
 
 LOG.info "[Brainiac] Starting v#{BRAINIAC_VERSION} on port #{settings.port} (#{settings.environment})"
+LOG.info "[Brainiac] Server root: #{SERVER_ROOT} (pid #{Process.pid})"
+
+# Warn loudly when the server is running from an installed gem rather than a git
+# checkout. During development this is almost always a mistake: `brainiac` on PATH
+# resolves to the gem's bin, so edits to a working checkout never take effect. Surfacing
+# it here turns a long "why won't my change apply" hunt into a one-line startup notice.
+if SERVER_ROOT.include?("/gems/")
+  LOG.warn "[Brainiac] Running from an installed GEM (#{SERVER_ROOT}) — not a git checkout. " \
+           "Local code changes will NOT be loaded. Run `ruby ./bin/brainiac server` from your checkout to test edits."
+end
 if intent_config["enabled"]
   LOG.info "[Intent] Enabled — model: #{intent_config["model"]}, endpoint: #{intent_config["endpoint"]}"
   begin

data/templates/cli-providers/kiro.json.example

@@ -18,5 +18,10 @@
     "qwen": "qwen3-coder-next",
     "auto": "auto"
   },
-  "efforts": ["low", "medium", "high", "xhigh", "max"]
+  "efforts": ["low", "medium", "high", "xhigh", "max"],
+  "heaviness_probe": {
+    "comment": "Optional. Lets brainiac record how 'heavy' a finished session was (context window usage + credits) in the durable session history. type selects the probe strategy; db_path points at the provider's local usage store. Omit this block to record timing/identity only.",
+    "type": "kiro_sqlite",
+    "db_path": "~/.local/share/kiro-cli/data.sqlite3"
+  }
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainiac
 version: !ruby/object:Gem::Version
-  version: 0.0.33
+  version: 0.1.0
 platform: ruby
 authors:
 - Andy Davis
@@ -142,6 +142,7 @@ files:
 - lib/brainiac/prompts.rb
 - lib/brainiac/restart.rb
 - lib/brainiac/routes/api.rb
+- lib/brainiac/session_history.rb
 - lib/brainiac/sessions.rb
 - lib/brainiac/skills.rb
 - lib/brainiac/users.rb