ask-agent 0.25.0 → 0.25.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbb7c5376d7ba7cf03099123c5aab9f12dd9a10efca9906fd07ea2782b28d296
-  data.tar.gz: 8c82d88e763cdf7e765fec8837b22ab5dc8a5a7cbaca01d9ffff59c8328a1e99
+  metadata.gz: ec5991dad0128d2383500176d9872d4fda5ac504f81826eeac343a1b8435616b
+  data.tar.gz: f62dd7104119cd637c2ca590bc8c3e7c7c6c32e8f85d2d0e7e2cc2cbd2e8b019
 SHA512:
-  metadata.gz: f886aedfbed678ce466c545e9f20255320a5ac77930c60d164613e833345455c52de0256f9c1a9357cda6040a79c2f17ed6aa687c5b8f135c6d355a50ecea5b6
-  data.tar.gz: be66be79539f4f284c8741ec634f17c4e5a12d18e4cc182209be5ac5f8988101589b10dfe331234cc1bb6880aa1a2c0af0ffbe4817b9ab382dd3fbcb2d6fd6b1
+  metadata.gz: 0ea8e0cf1e8750265f971b7379db7fddbc8c425d7f765835bc1d2b23e0fdf79001b2ceb93cc70e5647999e4327f6aa0ae3e56ed6708cdd8c66ea8e0006ddb039
+  data.tar.gz: bd758b33c296cd20fd90429d269fb079b5a1501b074c854d1dcfe27c007c2234b509693e7a136abf801738c775ed7c64894e2e2bc7c7414499f14ec2bbd6b416

data/CHANGELOG.md

@@ -1,3 +1,44 @@
+## [0.25.3] - 2026-08-04
+
+### Fixed
+
+- **Tools now respect the session's `parallel_tools` setting.** The agent
+  loop dispatched tool calls straight to `execute_parallel`, so tools always
+  ran in worker threads — even with `parallel_tools: false`. Sequential
+  sessions now run tools in the caller thread, which is what frameworks
+  like Rails rely on for per-request context (`CurrentAttributes` are
+  thread-local). The loop calls `ToolExecutor#execute`, which honors the
+  executor's `parallel` flag.
+- **Parallel tool threads inherit the caller's thread-local state.** When
+  tools do run in threads (parallel mode), `execute_parallel` copies the
+  caller's `Thread.current` locals into each worker thread first, so
+  per-request context (Rails `CurrentAttributes`, log tags, etc.) reaches
+  the tools instead of being nil.
+- `ToolExecutor#execute` accepts a `result_callback:` kwarg (invoked per
+  completed tool in both sequential and parallel modes); sequential
+  execution reports results through it too, matching parallel behavior.
+
+## [0.25.2] - 2026-08-03
+
+### Fixed
+
+- **Streaming no longer depends on ActiveSupport's `String#truncate`.** The
+  SSE event serialization (streaming.rb) and the max-consecutive-tool-turns
+  summary (loop.rb) called `String#truncate`, which only exists when
+  ActiveSupport's core extensions are loaded — so a bare `require
+  "ask-agent"` raised `NoMethodError` as soon as a tool emitted a partial
+  result. Both call sites now use a plain-Ruby truncation helper.
+
+## [0.25.1] - 2026-08-02
+
+### Fixed
+
+- **Session passes resolved tool instances to Chat.** Tool classes passed
+  as `tools: [MyTool]` were resolved for the session but handed to the
+  underlying Chat unresolved, so `ToolDef.from_tool` used `Class#name`
+  and raised `Ask::InvalidToolDefinition` on the first run. Sessions now
+  resolve tools before building the Chat; classes and instances both work.
+
 ## [0.25.0] — 2026-08-02
 
 ### Added

data/README.md

@@ -1,8 +1,9 @@
 # ask-agent
 
-Agent runtime for the ask-rb ecosystem. The core agent loop: think → call tools → execute → feed back → repeat.
-
-Ported from `RubyLLM::Conductor` into the `Ask::Agent` namespace.
+Agent runtime for the ask-rb ecosystem. Runs the core agent loop: think, call
+tools, execute, feed results back, and repeat until the task is done. Built on
+ask-core, ask-state-providers, ask-llm-providers, ask-tools, ask-skills, and
+ask-instrumentation, and it powers the `askr` CLI.
 
 ## Installation
 
@@ -15,114 +16,12 @@ gem "ask-agent"
 ```ruby
 require "ask-agent"
 
-session = Ask::Agent::Session.new(
-  model: "gpt-4o",
-  tools: [Ask::Tools::Shell::Bash, Ask::Tools::Shell::Read]
-)
-
+session = Ask::Agent::Session.new(model: "gpt-4o", max_turns: 25)
 response = session.run("What files are in the current directory?")
 puts response
 ```
 
-## Components
-
-| Component | File | Purpose |
-|---|---|---|
-| `Ask::Agent::Session` | session.rb | Full agent loop — message → tool calls → results → follow-up |
-| `Ask::Agent::Loop` | loop.rb | Turn management, loop detection, max-turn guard |
-| `Ask::Agent::ToolExecutor` | tool_executor.rb | Parallel/sequential tool execution with retry and abort |
-| `Ask::Agent::Compactor` | compactor.rb | Context window management with proactive/overflow compaction |
-| `Ask::Agent::Hooks` | hooks.rb | Before/after tool lifecycle callbacks |
-| `Ask::Agent::Events` | events.rb | Data.define event types for streaming and monitoring |
-| `Ask::Agent::Telemetry` | telemetry.rb | File-backed telemetry for error tracking |
-| `Ask::Agent::Reflector` | reflector.rb | Assistant response self-evaluation |
-| `Ask::Agent::MetaAgent` | meta_agent.rb | LLM-powered self-improvement from telemetry |
-| `Ask::Agent::Evaluator` | evaluator.rb | Independent response evaluation with structured rubric — different model, isolated context |
-| `Ask::Agent::Configuration` | configuration.rb | Global config: model, turns, concurrency, evaluator |
-
-## Evaluator
-
-Independent response evaluation with generator/evaluator separation. The
-evaluator uses a **separate model** (different from the session's model) and an
-**isolated context** to judge the agent's output — preventing the anti-pattern
-of a model grading its own work.
-
-### Quick start
-
-```ruby
-session = Ask::Agent::Session.new(
-  model: "gpt-4o",
-  evaluator: { model: "claude-sonnet-4", goal: "Write an email validator" }
-)
-session.run("Write email validation")
-```
-
-### Verdicts
-
-| Verdict | Behavior |
-|---------|----------|
-| `:accept` | Output passes — falls through to reflection |
-| `:revise` | Evaluator provides feedback; session runs another turn with it injected |
-| `:block` | Output is fundamentally wrong — returns blocked message, emits `EvaluationBlocked` |
-
-### Configuration
-
-```ruby
-# Set a global default evaluator model
-Ask::Agent.configure do |c|
-  c.default_evaluator_model = "claude-sonnet-4"
-end
-
-# Then use evaluator: true to enable with the default
-session = Ask::Agent::Session.new(model: "gpt-4o", evaluator: true)
-```
-
-### Custom rubric
-
-```ruby
-evaluator = Ask::Agent::Evaluator.new(
-  model: "claude-sonnet-4",
-  rubric: [
-    Ask::Agent::Evaluator::Dimension.new(
-      name: "performance",
-      description: "Is the implementation efficient?",
-      weight: 2
-    )
-  ]
-)
-
-result = evaluator.evaluate(
-  goal: "Write an email validator",
-  response: agent_output
-)
-result.accept?  # => true/false
-result.scores   # => { performance: 2 }
-result.feedback # => "Add edge case for unicode characters"
-```
-
-### Events
-
-The evaluator emits its own events during evaluation:
-
-```ruby
-session.on_event do |event|
-  case event
-  when Ask::Agent::Events::EvaluationStart
-    puts "Evaluating against: #{event.dimensions.join(', ')}"
-  when Ask::Agent::Events::EvaluationDelta
-    print event.content
-  when Ask::Agent::Events::EvaluationEnd
-    puts "Decision: #{event.decision}"
-    puts "Scores: #{event.scores}"
-  when Ask::Agent::Events::EvaluationBlocked
-    puts "Blocked: #{event.feedback}"
-  end
-end
-```
-
-## Events
-
-Stream session execution in real-time:
+Stream execution in real time with events:
 
 ```ruby
 session.on_event do |event|
@@ -131,95 +30,17 @@ session.on_event do |event|
     print event.content
   when Ask::Agent::Events::ToolExecutionStart
     puts "\nRunning #{event.name}..."
-  when Ask::Agent::Events::ToolExecutionEnd
-    puts "  → #{event.duration_ms}ms #{event.is_error ? 'error' : 'ok'}"
   end
 end
 ```
 
-## Extensions
-
-Opt-in safety modules:
-
-- **Permissions** — Access control for tools. Supports named access modes (`:full_access`, `:read_only`, `:ask_before_changes`) or custom blocked-tool lists.
-- **RateLimiter** — Prevent runaway tool calls (configurable per-minute and per-turn limits)
-- **AuditLog** — Immutable, append-only log of every tool call
-
-```ruby
-extensions = [
-  Ask::Agent::Extensions::Permissions.new(mode: :read_only),
-  Ask::Agent::Extensions::RateLimiter.new(max_calls_per_minute: 30),
-  Ask::Agent::Extensions::AuditLog.new(path: "agent.log")
-]
-
-session = Ask::Agent::Session.new(
-  model: "gpt-4o",
-  tools: [...],
-  hooks: {
-    before_tool: extensions.map(&:method(:before_tool_call)),
-    after_tool: extensions.select { |e| e.respond_to?(:after_tool_call) }.map(&:method(:after_tool_call))
-  }
-)
-```
-
-## Middleware
-
-Wrapping LLM provider calls with cross-cutting behavior:
-
-- **RetryOnFailure** — Retry on rate limits and server errors with exponential backoff
-- **ModelFallback** — Switch to a fallback model+provider on transient errors
-- **LogCalls** — Log every LLM provider call
-- **DefaultSettings** — Inject default generation parameters
-
-```ruby
-Ask::Agent.configure do |c|
-  c.middleware.use :retry_on_failure, max_retries: 3
-  c.middleware.use :model_fallback, fallbacks: [
-    { model: "claude-sonnet-4",  provider: :anthropic },
-    { model: "gemini-2.0-flash", provider: :google }
-  ]
-  c.middleware.use :log_calls, logger: Rails.logger
-  c.middleware.use :default_settings, temperature: 0.7
-end
-```
-
-### ModelFallback
-
-When the primary LLM is overloaded or down, `ModelFallback` transparently switches to a backup model+provider. Credentials for each provider are resolved automatically.
-
-**Static fallbacks** — ordered list tried in sequence:
-```ruby
-c.middleware.use :model_fallback, fallbacks: [
-  { model: "claude-sonnet-4",  provider: :anthropic },
-  { model: "gemini-2.0-flash", provider: :google }
-]
-```
-
-**Dynamic fallbacks** — lambda that receives the error and request:
-```ruby
-c.middleware.use :model_fallback, fallbacks: ->(error, request) {
-  if request[:messages].sum { |m| m[:content].to_s.length } > 100_000
-    [{ model: "claude-sonnet-4", provider: :anthropic }]  # long-context
-  else
-    [{ model: "gpt-4o-mini", provider: :openai }]           # cheaper
-  end
-}
-```
+## Declarative Agents
 
-**Custom eligible errors** — by default rate limits, server errors, and service unavailable:
-```ruby
-c.middleware.use :model_fallback,
-  fallbacks: [{ model: "claude-sonnet-4", provider: :anthropic }],
-  eligible_errors: [Ask::RateLimitError, Ask::ServerError]
-```
-
-## Agents
-
-Declarative agents follow a file convention. Each agent lives in a
-directory under `agents/` (or `app/agents/` in Rails); the directory
-name is the agent name, the file `agent.rb` defines the agent as a
-`<Name>::Agent < Ask::Agent::Definition` subclass, and a sibling
-`instructions.md` is auto-loaded as the system prompt.
+Agents follow a file convention. Each agent lives in a directory under
+`agents/` (or `app/agents/` in Rails); the directory name is the agent name,
+the file `agent.rb` defines the agent as a `<Name>::Agent <
+Ask::Agent::Definition` subclass, and a sibling `instructions.md` is
+auto-loaded as the system prompt.
 
 ```
 agents/
@@ -246,10 +67,22 @@ agent = Ask::Agent.new("health_check")
 response = agent.run("Check server health")
 ```
 
-Shared tools for all agents go in `agents/shared/tools/`. Per-agent
-skills go in `agents/<name>/skills/`, shared skills in `agents/shared/skills/`.
+Shared tools for all agents go in `agents/shared/tools/`. Per-agent skills go
+in `agents/<name>/skills/`, shared skills in `agents/shared/skills/`.
+
+## Essential API
+
+| Entry point | Purpose |
+|---|---|
+| `Ask::Agent::Session.new(model:, tools: [], max_turns: 25, ...)` | Full agent loop: message, tool calls, results, follow-up |
+| `session.run(message)` | Run the loop for one message |
+| `session.on_event { \|e\| }` | Stream `Ask::Agent::Events` (text deltas, tool execution, evaluation) |
+| `Ask::Agent.new("name")` | Build a session from a declarative agent definition |
+| `Ask.chat(message)` | One-shot chat without instantiating a Session |
+| `Ask::Agent.configure { \|c\| ... }` | Global defaults: model, provider, turns, compactor, middleware |
+| `askr` | CLI: `askr run <agent> [prompt]`, `askr list`, `askr schedule`, `askr new`, `askr skills` |
 
-## Configuration
+### Configuration
 
 ```ruby
 Ask::Agent.configure do |c|
@@ -263,26 +96,23 @@ Ask::Agent.configure do |c|
 end
 ```
 
-`default_provider` pins which provider serves the default model when the
-model name doesn't uniquely identify one (for example, the same model id
-registered under multiple OpenAI-compatible providers). A `provider:`
-passed to `Session.new` or declared in an agent `Definition` always wins
-over the global default.
+`default_provider` pins which provider serves the default model when the model
+name doesn't uniquely identify one (for example, the same model id registered
+under multiple OpenAI-compatible providers). A `provider:` passed to
+`Session.new` or declared in an agent `Definition` always wins over the global
+default.
 
-## Persistence
+## Full documentation
 
-```ruby
-store = Ask::Agent::Persistence::InMemory.new
-session = Ask::Agent::Session.new(model: "gpt-4o", persistence: store)
-session.run("Hello")
-session.save  # persisted to store
-```
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.
+https://ask-rb.github.io/ask-docs/core/agent covers ask-agent in depth,
+including the evaluator, middleware, extensions, cost tracking, and
+persistence. API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 
-```bash
+bundle install
 bundle exec rake test
-```
 
 ## License
 

data/lib/ask/agent/context_source.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require "time"
 
 module Ask
   module Agent

data/lib/ask/agent/context_sources.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require "time"
 
 module Ask
   module Agent

data/lib/ask/agent/extensions/audit_log/active_record_writer.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require "time"
 
 module Ask
   module Agent

data/lib/ask/agent/extensions/audit_log.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "time"
 
 module Ask
   module Agent

data/lib/ask/agent/loop.rb

@@ -79,12 +79,17 @@ module Ask
 
         if user_tool_calls.any?
           # Execute user tool calls locally
-          user_results = tool_executor.execute_parallel(
-            user_tool_calls, tools, hooks, event_emitter, ToolAbortController.new
-          ) do |tool_call_id, result|
-            tc = user_tool_calls[tool_call_id]
-            chat.add_message(role: :tool, content: result[:message].to_s, tool_call_id: tool_call_id) if tc
-          end
+          # Respect the session's parallel_tools setting: parallel tools run
+          # in threads (with the caller's thread-local context inherited);
+          # sequential tools run in the caller thread so per-request context
+          # (e.g. Rails CurrentAttributes) is visible without any copying.
+          user_results = tool_executor.execute(
+            user_tool_calls, tools, hooks: hooks, event_emitter: event_emitter,
+            result_callback: lambda do |tool_call_id, result|
+              tc = user_tool_calls[tool_call_id]
+              chat.add_message(role: :tool, content: result[:message].to_s, tool_call_id: tool_call_id) if tc
+            end
+          )
           all_tool_results.concat(user_results)
         end
 
@@ -94,7 +99,7 @@ module Ask
         end
 
         if @consecutive_tool_turns >= @max_consecutive_tool_turns
-          summary = all_tool_results.map { |r| r[:message].to_s.truncate(80) }.first(2).join("; ")
+          summary = all_tool_results.map { |r| truncate(r[:message], 80) }.first(2).join("; ")
           return "Based on my investigation: #{summary}"
         end
 
@@ -137,6 +142,15 @@ module Ask
 
       private
 
+      # Truncate a string for summaries without depending on ActiveSupport's
+      # String#truncate (which is not loaded by a bare `require "ask-agent"`).
+      def truncate(text, length)
+        s = text.to_s
+        return s if s.length <= length
+
+        "#{s[0, length - 3]}..."
+      end
+
       def loop_detected?(results)
         return false if results.empty?
 

data/lib/ask/agent/meta_agent.rb

@@ -2,6 +2,7 @@
 
 require "set"
 require "json"
+require "time"
 
 module Ask
   module Agent

data/lib/ask/agent/session.rb

@@ -41,8 +41,8 @@ module Ask
 
         @telemetry = telemetry.is_a?(Telemetry) ? telemetry : Telemetry.new(enabled: !!telemetry)
 
-        @chat = build_chat(model, system_prompt, tools, **chat_options)
         @tools = resolve_tools(tools)
+        @chat = build_chat(model, system_prompt, @tools, **chat_options)
         @loop = Loop.new(max_turns: max_turns)
         @tool_executor = ToolExecutor.new(max_retries: max_tool_retries, parallel: parallel_tools)
         @compactor = compactor ? build_compactor(compactor) : nil

data/lib/ask/agent/streaming.rb

@@ -82,6 +82,15 @@ module Ask
 
         private
 
+        # Truncate a string for telemetry without depending on ActiveSupport's
+        # String#truncate (which is not loaded by a bare `require "ask-agent"`).
+        def truncate(text, length)
+          s = text.to_s
+          return s if s.length <= length
+
+          "#{s[0, length - 3]}..."
+        end
+
         def run_with_block(session, prompt, mapping)
           errors = []
 
@@ -154,7 +163,7 @@ module Ask
           when Events::ToolExecutionStart
             { name: event.name, id: event.id, args: safe_args(event.arguments) }
           when Events::ToolExecutionUpdate
-            { id: event.id, partial_result: event.partial_result.to_s.truncate(200) }
+            { id: event.id, partial_result: truncate(event.partial_result, 200) }
           when Events::ToolExecutionEnd
             { name: event.name, id: event.id, duration_ms: event.duration_ms, is_error: event.is_error }
           when Events::SessionEnd

data/lib/ask/agent/telemetry.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require "json"
 require "securerandom"
+require "time"
 
 module Ask
   module Agent

data/lib/ask/agent/tool_executor.rb

@@ -19,7 +19,7 @@ module Ask
 
       attr_writer :telemetry
 
-      def execute(tool_calls, tools, hooks:, event_emitter:, session_id: nil)
+      def execute(tool_calls, tools, hooks:, event_emitter:, session_id: nil, result_callback: nil)
         return [] if tool_calls.empty?
 
         @total_executions = 0
@@ -27,9 +27,11 @@ module Ask
         sibling_abort = ToolAbortController.new
 
         if @parallel
-          execute_parallel(tool_calls, tools, hooks, event_emitter, sibling_abort)
+          execute_parallel(tool_calls, tools, hooks, event_emitter, sibling_abort, &result_callback)
         else
-          execute_sequential(tool_calls, tools, hooks, event_emitter, sibling_abort)
+          execute_sequential(tool_calls, tools, hooks, event_emitter, sibling_abort) do |id, result|
+            result_callback&.call(id, result)
+          end
         end
       end
 
@@ -38,8 +40,15 @@ module Ask
         mutex = Mutex.new
         results = {}
 
+        # Inherit the caller's thread-local state (Rails CurrentAttributes
+        # and similar frameworks store per-request context in Thread.current)
+        # so tools see the same context they would in a sequential run.
+        inherited_locals = {}
+        Thread.current.keys.each { |key| inherited_locals[key] = Thread.current[key] }
+
         tool_calls.each do |id, tool_call|
           threads << Thread.new do
+            inherited_locals.each { |key, value| Thread.current[key] = value }
             begin
               if sibling_abort.aborted?
                 mutex.synchronize { results[id] = aborted_result(tool_call) }
@@ -75,13 +84,14 @@ module Ask
         tool_calls.keys.map { |id| results[id] }.compact
       end
 
-      def execute_sequential(tool_calls, tools, hooks, event_emitter, sibling_abort)
+      def execute_sequential(tool_calls, tools, hooks, event_emitter, sibling_abort, &result_callback)
         results = []
         tool_calls.each do |id, tool_call|
           break if sibling_abort.aborted?
 
           result = execute_single_tool(tool_call, tools, hooks, event_emitter, sibling_abort)
           results << result
+          result_callback&.call(id, result)
           break if result[:critical_failure]
           break if result[:halted]
         end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.25.0"
+    VERSION = "0.25.3"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.25.3
 platform: ruby
 authors:
 - Kaka Ruto