brainiac 0.1.10 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e63254b890e44045e1c05872417234f86e34fdcd36a737c7565c4ee7efc74426
-  data.tar.gz: 630399ccb91dc4ef99b6f14619710c5893b6194354dc3a89f3d491cc4b226bdb
+  metadata.gz: c65982d3a8149b7e0378221a00612218c0d77df2fe0c82370aa7210210f125d3
+  data.tar.gz: 4fcccf1bb797b144f6382a3562e5837ada64af5d1fc3ef3abc13b8f68a3d6818
 SHA512:
-  metadata.gz: d0a1f9cc0ca39aa87aec48c3b45132b7777e6dc6ca7f71006a78e6ebe00879c188d8cea9104822d2e32a3d1b65970d09d5271c558d5af10faa8d29a24bd182a5
-  data.tar.gz: '02884d9354a9b5946a28f58f0e0c70d4f98893554b773f1738aa6e2a9383850d4f7577c8d691c9ef11867f71a81c5327a5ac28922fc7b90a95311bb1ceb536c4'
+  metadata.gz: 82764530696b3843f4723f6169e3026fb9540c5e78c833bc66cbb8642851bc70496404de3479426dc3a624197903735a4cd0b210396e06b7e81076a37467561a
+  data.tar.gz: 29e3a1a6c736f0f2cbb82908262f049aaddd5e59ded8eafb21854eae5d7f8cb83ea63c3e58df7b46bc165e0b9e681d3e4f696f09ef9a0a8994eba829b4b36497

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)
 

data/lib/brainiac/version.rb

@@ -2,5 +2,5 @@
 
 module Brainiac
   # @return [String] the current gem version
-  VERSION = "0.1.10"
+  VERSION = "0.2.1"
 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/receiver.rb

@@ -22,6 +22,7 @@ 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/ask"
 require_relative "lib/brainiac/notifications"
 require_relative "lib/brainiac/cron"
 require_relative "lib/brainiac/restart"

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.10
+  version: 0.2.1
 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