brainiac 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cedcfe4e4dfa26034cf0ded9746d8ff5bade886ec3d83774580d8334777d4d3c
-  data.tar.gz: 96d1702d994f06f0a4f41870de6652258fc700a9f9df1b6193c347b2cce3b365
+  metadata.gz: 3d90a30fad5756179777b90413b87bbd41550783c75c2e9a38f726e1a2e1ef5c
+  data.tar.gz: 32607dc0510acec6449bdb16e8a4acbec358caa94a0d8592d7a6d06e4f73e9a2
 SHA512:
-  metadata.gz: 16a5c9937e67afe78bcba468dea8a4b75c73864c4a320b8d2da930a966bd618797b6285f765f772a99394d8925ba9438fe2b9012ccb94730908e97642148cdbb
-  data.tar.gz: 95cd9275779731da352b0356e1da275f12511b960037512e829614a6b5e2a4a97e3b00ba0ceeefbdbcc8eff71a3f0717b9cc43fb3ee4d21b2b706361e4dfccc0
+  metadata.gz: 1a16401ff3896e546d5411785418228ef5ef2a360dc10fd3633a798723969d90a7d5668d8f8e908856a08bdac35e939519f94bcb79ad6f2f259d0f55dac9c525
+  data.tar.gz: 29947e9e2dacd7007a630a06be63e7e8dbc913f9e677b28ccf92a5dcf4c3659c189291c7d07971b42e06c6c0d08880d266854aa759721d701308a415dfdbb79f

data/README.md

@@ -202,7 +202,7 @@ After setup, `~/.brainiac/` looks like:
 
 ```
 ~/.brainiac/
-├── brainiac.json        # Core config (default_agent)
+├── brainiac.json        # Core config (default_agent, default_cli_provider)
 ├── agents.json          # Agent registry (tokens, display names, local flag)
 ├── projects.json        # Registered projects
 ├── users.json           # Cross-platform user identity registry
@@ -262,6 +262,31 @@ The `agent_flag` field controls how agent identity is passed to the CLI. Differe
 
 Set `agent_flag` to `null` to suppress passing the agent name entirely (for CLIs that don't support persona switching).
 
+`readonly_args` is optional. It replaces `default_args` when a plugin asks an agent something with `readonly: true` (see [Asking an agent from a plugin](#asking-an-agent-from-a-plugin)), so it must only allow tools that read:
+
+| CLI | `readonly_args` |
+|-----|-----------------|
+| Kiro CLI | `chat --no-interactive --trust-tools=fs_read` |
+| Claude Code | `-p --restricted --strict-mcp-config --no-session-persistence --tools Read,Grep,Glob` |
+
+A provider without `readonly_args` can't be used read-only; the call fails instead of falling back to `default_args`.
+
+Which provider runs is decided in this order: a `[cli:X]` tag, the agent's `cli_provider` in `agents.json`, the project's `cli_provider`, then `default_cli_provider` in `brainiac.json`. With none of those set, brainiac uses the `AGENT_CLI` env var, or kiro-cli.
+
+#### Asking an agent from a plugin
+
+`run_agent` starts a session and returns straight away. When a plugin needs the agent's answer back (for example to decide whether an incoming report is a bug), it calls `ask_agent`, which waits and returns the reply text:
+
+```ruby
+reply = ask_agent(prompt, project_config: PROJECTS["my-app"], project_key: "my-app",
+                          readonly: true, topic: "bug triage", timeout: 300)
+```
+
+- The agent and CLI resolve the same way as `run_agent`: `agent_name:`, else the project's `agent_name`, else the default agent.
+- `brain: true` (the default) puts the agent's role, persona and brain knowledge ahead of the prompt. `topic:` seeds the knowledge search.
+- `readonly: true` runs the provider's `readonly_args`. Use it whenever the prompt contains text from outside (webhooks, emails, public forms).
+- It raises `AskAgentError` on a timeout, a CLI failure, or a read-only request to a provider without `readonly_args`.
+
 Brainiac ships with example providers during setup. Your project config references which provider to use.
 
 #### 3. Environment Variables
@@ -269,10 +294,12 @@ Brainiac ships with example providers during setup. Your project config referenc
 Most config lives in JSON files now. The default agent is set in `brainiac.json`:
 
 ```json
-{ "default_agent": "Sherlock" }
+{ "default_agent": "Sherlock", "default_cli_provider": "kiro" }
 ```
 
-Or via environment variable (takes precedence):
+`default_cli_provider` is the CLI used when neither the agent nor the project names one (see [CLI Providers](#2-cli-providers-brainiaccli-providers)).
+
+The default agent can also be set via environment variable (takes precedence):
 
 ```bash
 export AI_AGENT_NAME="Sherlock"

data/lib/brainiac/ask.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# ask_agent: a synchronous, one-off agent call for plugins that need the answer back
+# (e.g. deciding whether an incoming report is a bug). run_agent spawns a session and
+# returns before there's any output, so it can't do this.
+
+class AskAgentError < StandardError; end
+
+ANSI_ESCAPE = %r{\e\[[0-9;?]*[ -/]*[@-~]}
+
+# Ask an agent a question and return its reply as text.
+#
+# The agent and CLI resolve the same way run_agent's do: agent_name, else the project's
+# agent_name, else the default agent; cli_provider, else the agent's, the project's, then
+# brainiac.json's default_cli_provider.
+#
+# brain: true puts the agent's role, persona and brain knowledge ahead of the prompt, so the
+#   whole agent answers rather than a bare model. topic seeds the knowledge search.
+# readonly: true runs the provider's readonly_args instead of default_args. Raises
+#   AskAgentError when the provider has none: text from strangers must never reach an agent
+#   that can write files or run commands, so there's no falling back to default_args.
+#
+# Raises AskAgentError when the CLI times out or exits non-zero without a reply.
+def ask_agent(prompt, project_config:, agent_name: nil, chdir: nil, readonly: false, brain: true, topic: "",
+              project_key: nil, model: nil, cli_provider: nil, timeout: 300, log_name: "ask")
+  agent_name ||= project_config["agent_name"] || AI_AGENT_NAME
+  resolved = ask_agent_cli_config(project_config, cli_provider: cli_provider, agent_name: agent_name, readonly: readonly)
+  chdir ||= resolved["repo_path"]
+  raise AskAgentError, "working directory #{chdir.inspect} doesn't exist" unless chdir && Dir.exist?(chdir)
+
+  if brain
+    context = build_brain_context(agent_name: agent_name, card_title: topic, project_key: project_key)
+    prompt = "#{context}\n## Task\n\n#{prompt}" unless context.empty?
+  end
+
+  timestamp = Time.now.strftime("%Y%m%d-%H%M%S")
+  prompt_file = write_agent_prompt_file(prompt, log_name, timestamp)
+  output_file = prepare_output_file(resolved, log_name, timestamp)
+  cmd = build_agent_cmd(resolved, agent_config_name: agent_name.downcase.gsub(/[^a-z0-9-]/, "-"),
+                                  model: model || resolved["agent_model"], prompt_file: prompt_file,
+                                  output_file: output_file, chdir: chdir)
+  LOG.info "[Ask] #{agent_name} via #{resolved["agent_cli"]}#{" (read-only)" if readonly} in #{chdir}: #{cmd.join(" ")}"
+
+  stdout = run_ask_command(cmd, prompt_file, resolved, chdir: chdir, env: profile_spawn_env(agent_env_for(agent_name), nil),
+                                                       timeout: timeout)
+  (read_output_file(output_file) || stdout).gsub(ANSI_ESCAPE, "").strip
+ensure
+  FileUtils.rm_f(prompt_file) if prompt_file
+end
+
+# The resolved CLI config, with readonly_args swapped in for default_args when asked.
+def ask_agent_cli_config(project_config, cli_provider:, agent_name:, readonly:)
+  resolved = resolve_project_cli_config(project_config, cli_provider_override: cli_provider, agent_name: agent_name)
+  return resolved unless readonly
+
+  args = resolved["readonly_args"]
+  if args.to_s.strip.empty?
+    raise AskAgentError, "#{resolved["agent_cli"]} has no readonly_args in its cli-providers config, " \
+                         "so it can't be run read-only"
+  end
+
+  resolved.merge("agent_cli_args" => args)
+end
+
+# Run the CLI and return its stdout. Kills the whole process group on timeout so the
+# CLI's own children (tool calls, MCP servers) go with it.
+def run_ask_command(cmd, prompt_file, resolved, chdir:, env:, timeout:)
+  stdin_data = resolved["prompt_mode"] == "flag" ? "" : File.read(prompt_file)
+  Open3.popen3(env, *cmd, chdir: chdir, pgroup: true) do |stdin, stdout, stderr, wait|
+    readers = [Thread.new { stdout.read }, Thread.new { stderr.read }]
+    begin
+      stdin.write(stdin_data)
+    rescue Errno::EPIPE
+      nil # CLI exited before reading the prompt; its exit status says why.
+    end
+    stdin.close
+
+    unless wait.join(timeout)
+      begin
+        Process.kill("TERM", -wait.pid)
+      rescue Errno::ESRCH
+        nil # Finished just as the clock ran out.
+      end
+      readers.each(&:join) # The kill closes the pipes, so these return.
+      raise AskAgentError, "#{resolved["agent_cli"]} timed out after #{timeout}s"
+    end
+
+    out, err = readers.map(&:value)
+    if !wait.value.success? && out.strip.empty?
+      raise AskAgentError, "#{resolved["agent_cli"]} exited #{wait.value.exitstatus}: #{err.strip.lines.last(5).join}"
+    end
+
+    out
+  end
+end

data/lib/brainiac/config.rb

@@ -80,6 +80,13 @@ end
 
 AI_AGENT_NAME = resolve_default_agent
 
+# --- Default CLI provider ---
+# Last fallback for which CLI runs an agent, after the agent's and the project's
+# cli_provider. Unset → DEFAULT_PROJECT's AGENT_CLI env var / kiro-cli.
+def default_cli_provider
+  BRAINIAC_CONFIG["default_cli_provider"]
+end
+
 LOG_LEVEL = ENV.fetch("LOG_LEVEL", "info").downcase
 LOG = Logger.new($stdout)
 LOG.level = case LOG_LEVEL

data/lib/brainiac/helpers.rb

@@ -32,7 +32,7 @@ def load_cli_provider(provider_name)
   config["prompt_mode"] = raw["prompt_mode"] || "stdin"
   # Copy optional fields from raw config when present.
   # Each field controls a specific CLI behavior — see comments in the template.
-  %w[prompt_flag list_models_command resume_flag resume_args resume_id_flag new_session_id_flag
+  %w[prompt_flag readonly_args 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 heaviness_probe settings_model_cmd].each do |key|
@@ -76,12 +76,14 @@ end
 require_relative "model_parser"
 
 # Resolve CLI config for a project by merging provider defaults with project overrides.
-# Priority: cli_provider_override > agent-level cli_provider > project-level cli_provider > DEFAULT_PROJECT
+# Priority: cli_provider_override > agent-level cli_provider > project-level cli_provider >
+# brainiac.json default_cli_provider > DEFAULT_PROJECT
 def resolve_project_cli_config(project_config, cli_provider_override: nil, agent_name: nil)
-  # Determine which CLI provider to use (priority: override > agent > project)
+  # Determine which CLI provider to use (priority: override > agent > project > default)
   provider_name = cli_provider_override
   provider_name ||= agent_cli_provider_for(agent_name) if agent_name
   provider_name ||= project_config["cli_provider"]
+  provider_name ||= default_cli_provider
 
   provider_config = load_cli_provider(provider_name)
 
@@ -704,9 +706,11 @@ def prior_session_exists?(chdir, agent_cli, session_dir: nil)
   return true if File.directory?(session_dir_local)
 
   # Fallback: look for recent session logs in tmp/ that suggest this CLI ran here before.
-  # This covers CLIs that don't leave a dotdir but do leave logs via brainiac.
+  # This covers CLIs that don't leave a dotdir but do leave logs via brainiac. The logs
+  # don't say which CLI wrote them, so only trust them when the last-CLI marker says it was this one.
   tmp_dir = File.join(chdir, "tmp")
   return false unless File.directory?(tmp_dir)
+  return false unless last_cli_for(chdir) == cli_name
 
   Dir.glob(File.join(tmp_dir, "agent-*.log")).any? do |log|
     # Only count logs from the last 24 hours as valid "resumable" sessions
@@ -716,6 +720,40 @@ rescue StandardError
   false
 end
 
+# Marker recording which CLI binary last ran in a directory (written by run_agent).
+def last_cli_marker_path(chdir)
+  File.join(chdir, "tmp", ".brainiac-last-cli")
+end
+
+def last_cli_for(chdir)
+  return nil unless chdir
+
+  name = File.read(last_cli_marker_path(chdir)).strip
+  name.empty? ? nil : name
+rescue StandardError
+  nil
+end
+
+def record_last_cli(chdir, agent_cli)
+  key = cli_session_key(agent_cli)
+  return unless chdir && key
+
+  FileUtils.mkdir_p(File.join(chdir, "tmp"))
+  File.write(last_cli_marker_path(chdir), key)
+rescue StandardError => e
+  LOG.warn "[Dispatch] Could not record last CLI for #{chdir}: #{e.message}"
+end
+
+# True when a different CLI ran in this directory more recently than agent_cli.
+# A switched-to CLI never saw the other provider's turns, so resuming its own (older)
+# session would hand it a lean prompt with a stale or empty history. Start fresh instead
+# and let the full prompt (memory file + source context) carry the conversation.
+def cli_switched_since_last_run?(chdir, agent_cli)
+  last = last_cli_for(chdir)
+  key = cli_session_key(agent_cli)
+  !last.nil? && !key.nil? && last != key
+end
+
 # Check if a centralized session directory has sessions matching the given cwd.
 # Supports CLIs that store sessions as .jsonl files in date-partitioned directories (YYYY/MM/DD/)
 # with a first-line JSON metadata object containing a "payload.cwd" field.
@@ -777,6 +815,7 @@ end
 def resume_viable?(project_config:, cli_provider: nil, agent_name: nil, chdir: nil)
   resolved = resolve_project_cli_config(project_config, cli_provider_override: cli_provider, agent_name: agent_name)
   chdir ||= resolved["repo_path"]
+  return false if cli_switched_since_last_run?(chdir, resolved["agent_cli"])
   return stored_cli_session_viable?(resolved, chdir) if resolved["resume_id_flag"]
   return false unless resolved["resume_flag"] || resolved["resume_args"]
 
@@ -805,6 +844,11 @@ end
 def resolve_resume(resume, resolved, chdir, session_id: nil)
   return false unless resume
 
+  if cli_switched_since_last_run?(chdir, resolved["agent_cli"])
+    LOG.info "[Dispatch] CLI switched from #{last_cli_for(chdir)} to #{resolved["agent_cli"]} in #{chdir} — starting fresh session"
+    return false
+  end
+
   if resolved["resume_id_flag"]
     id = session_id.to_s.empty? ? cli_session_id_for(agent_cli: resolved["agent_cli"], worktree: chdir) : session_id
     if id.to_s.empty?
@@ -824,16 +868,27 @@ def resolve_resume(resume, resolved, chdir, session_id: nil)
   false
 end
 
-# Some CLIs (e.g. grok --session-id) let the caller name a new session up front.
-# Mint a UUID only on the first run, when we are not resuming an existing id.
-def mint_cli_session_id(resolved, stored_session:, resuming:)
+# Some CLIs (e.g. claude/grok --session-id) let the caller name a new session up front.
+# Mint a UUID whenever we start fresh — including after a provider switch, when an older
+# stored id exists — so the stored id always points at the latest session for this CLI.
+def mint_cli_session_id(resolved, resuming:)
   return nil if resuming
   return nil unless resolved["new_session_id_flag"]
-  return nil unless stored_session.to_s.empty?
 
   SecureRandom.uuid
 end
 
+# Decide resume vs. fresh start for this dispatch, then record this CLI as the last
+# one to run here. Returns [should_resume, minted_session_id].
+def prepare_cli_session(resume, resolved, chdir)
+  stored_session = cli_session_id_for(agent_cli: resolved["agent_cli"], worktree: chdir)
+  # Auto-resume: only if the provider supports it AND a prior session exists for this CLI here.
+  should_resume = resolve_resume(resume, resolved, chdir, session_id: stored_session)
+  minted_session_id = mint_cli_session_id(resolved, resuming: should_resume)
+  record_last_cli(chdir, resolved["agent_cli"])
+  [should_resume, minted_session_id]
+end
+
 # Check if intent detection says to skip dispatching the agent.
 # Returns true if the message should be skipped, false otherwise.
 # Only runs if a raw message is provided, an agent is named, and intent is enabled.
@@ -870,12 +925,8 @@ def run_agent(prompt, project_config:, chdir: nil, log_name: "agent", model: nil
   effort ||= resolved["agent_effort"]
   agent_config_name = agent_name&.downcase&.gsub(/[^a-z0-9-]/, "-")
 
-  stored_session = cli_session_id_for(agent_cli: resolved["agent_cli"], worktree: chdir)
   work_item_id = find_work_item_by_worktree(chdir)&.first
-
-  # Auto-resume: only if the provider supports it AND a prior session exists for this CLI here.
-  should_resume = resolve_resume(resume, resolved, chdir, session_id: stored_session)
-  minted_session_id = mint_cli_session_id(resolved, stored_session: stored_session, resuming: should_resume)
+  should_resume, minted_session_id = prepare_cli_session(resume, resolved, chdir)
 
   # Pre-dispatch hook — plugins can prep the working directory (e.g., copy config files, clean up)
   Brainiac.emit(:pre_dispatch, chdir: chdir, project_config: project_config, agent_name: agent_name)

data/lib/brainiac/version.rb

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

data/lib/brainiac.rb

@@ -9,6 +9,7 @@ require_relative "brainiac/sessions"
 require_relative "brainiac/session_history"
 require_relative "brainiac/prompts"
 require_relative "brainiac/helpers"
+require_relative "brainiac/ask"
 require_relative "brainiac/intent"
 require_relative "brainiac/cron"
 require_relative "brainiac/plugins"

data/templates/brainiac.json.example

@@ -1,5 +1,6 @@
 {
   "default_agent": "Sherlock",
+  "default_cli_provider": "kiro",
   "intent": {
     "enabled": false,
     "endpoint": "http://localhost:11434/api/generate",

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

@@ -1,6 +1,7 @@
 {
   "binary": "kiro-cli",
   "default_args": "chat --trust-all-tools --no-interactive",
+  "readonly_args": "chat --no-interactive --trust-tools=fs_read",
   "agent_flag": "--agent",
   "model_flag": "--model",
   "effort_flag": "--effort",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainiac
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.0
 platform: ruby
 authors:
 - Andy Davis
@@ -126,6 +126,7 @@ files:
 - docs/waybar-config.md
 - lib/brainiac.rb
 - lib/brainiac/agents.rb
+- lib/brainiac/ask.rb
 - lib/brainiac/brain.rb
 - lib/brainiac/config.rb
 - lib/brainiac/cron.rb