activeagent 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f352ce28ead5e975e8d64c76c4a263c1ac7cac3b202ea6fef1a137f899e3aea0
-  data.tar.gz: d163e4360d38fdf440465ec0caf76dc9c196cab342de0de4cf67de020b31d0e2
+  metadata.gz: 45044ca9e6ddabcdfb1be0f32074149a3e9fb8fcaa9e7c8a79c02f81c73eb64b
+  data.tar.gz: 7f0a2489a68e01f0dd0e9a1fb96878bb900acaab173ba0a0157ad82a8a510fe6
 SHA512:
-  metadata.gz: 8aed9bb0e1d7bec5b5e178940e4e43c8a117c82d36db703d34cbef485b0492d29d628350bb956cf709ee504a81327e152d5510d3c1b81cf43d5ecc70f33ffae8
-  data.tar.gz: 6d8b3c9b6d6f7286985206a42db8949067dbb46bc39db67e4eb507ccc1a9dd405ed46720c06878c4d5ea748f8da184072ce4e9bf9951361d4fe5172ae65770d8
+  metadata.gz: 7c4797fc3bc8e97be8624ef989abc1486fe0d357f5248353dd09bc9852de605e0b14cebb33f3fb35ba166f62e64f7ce5522f62da94ad25b5b188a771f1f8aeec
+  data.tar.gz: 72bc8b89a042c1d3fd2489de0eb452d2e95106eaf9a46ad4dc5e8f1378b3441345c0b652c123490804943064f16526a1baa67584ce4b2a4315255beb3783203e

data/CHANGELOG.md

@@ -5,6 +5,152 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2026-08-18
+
+### Added
+
+- **Agent-as-tool delegation.** A tool is a Ruby method the model can call; a
+  delegation is another agent it can call. The callee keeps its own
+  instructions, templates, model and budget, so a specialist agent stays
+  specialist and the generalist orchestrating it never inherits its prompt.
+  Declared with `delegation :action, description:` on the sub-agent, with a
+  JSON Schema for the inputs and an optional `returns` schema that becomes the
+  sub-agent's response format. See `docs/actions/delegation.md`.
+
+### Fixed
+
+- **Streamed generations report their token usage.** A request with
+  `stream: true` recorded zero input and output tokens, and so zero cost and
+  no context-pressure estimate downstream — dashboards showed `Tokens 0` and
+  `$0.00` beside a run that had plainly called the API. Three things had to
+  hold at once for the usage to survive, and none did: the streaming path
+  returns `nil` rather than a response body to read usage from; Chat
+  Completions only emits its usage chunk when the request sets
+  `stream_options: {include_usage: true}`, which was never sent; and that
+  chunk arrives *after* `content.done`, where the response was already being
+  built. Completion now defers until the stream drains, and the usage chunk
+  is recorded on the way past. A provider hook (`api_stream_usage_parameters`,
+  empty by default) keeps providers that report unconditionally — or not at
+  all — unaffected.
+
+  Also fixed a silent conversion failure behind the same symptom:
+  `Usage.from_provider_usage` early-returns on anything that is not a Hash,
+  and the stainless gems hand back model objects, so usage was dropped even
+  when it did arrive.
+
+### Note on the 1.2.0 tag
+
+The `v1.2.0` tag had been moved to a commit later than the one published as
+`activeagent 1.2.0`, so the tag and the gem disagreed. It has been repointed
+to the commit that actually produced the release. If you fetched the tag
+between 2026-08-14 and 2026-08-18, re-fetch with `git fetch --tags --force`.
+
+## [1.2.2] - 2026-08-14
+
+### Fixed
+
+- **`actionagent`: every engine constant resolves under a host's
+  inflections.** 1.2.1 scoped its autoloader override to the basename `api`,
+  which covered the controllers under `app/controllers/action_agent/api` and
+  nothing else. Seven files camelize differently once a host registers an
+  acronym — `mcp_catalog.rb`, `mcp_recording_middleware.rb`,
+  `playwright_mcp_client.rb`, `api_key.rb`, and the `api_keys`, `mcp` and
+  `mcp_servers` controllers — and each raised `Zeitwerk::NameError` on first
+  reference. In a host declaring `inflect.acronym "MCP"` the **Tools view was
+  unreachable** (`uninitialized constant
+  ActionAgent::ToolDiscovery::McpCatalog`), as were the MCP endpoints and
+  anything touching an API key.
+
+  Every path under the engine now camelizes with Zeitwerk's default
+  inflector, ignoring the host's acronyms, scoped by path so the host's own
+  constants keep their spelling. The router half generalizes with it: an
+  all-caps run in a missing constant is retried in the relaxed spelling
+  (`API` → `Api`, `MCPServersController` → `McpServersController`) rather
+  than aliasing each pair by hand.
+
+## [1.2.1] - 2026-08-14
+
+### Fixed
+
+- **`actionagent`: the install migrations now run on MySQL.** Both templates
+  already chose the JSON column type per adapter, but kept `default: []` /
+  `default: {}` for every adapter, and MySQL rejects a default on a JSON
+  column outright — so `rails g action_agent:install && rails db:migrate`
+  aborted mid-`create_table` on any MySQL host. The default (and the paired
+  `null: false`, which without it would reject the inserts the default
+  existed to satisfy) is now PostgreSQL-only. Every JSON column is read
+  through `Array(...)` / `|| {}`, so a NULL reads as the empty value.
+- **`actionagent`: the mount works in a host that declares
+  `inflect.acronym "API"`.** An engine's files are autoloaded under the
+  host's inflections, so such a host made Zeitwerk expect
+  `ActionAgent::API::TracesController` from a file defining
+  `ActionAgent::Api::TracesController`, and every request to the mount
+  raised `Zeitwerk::NameError`. Rails separately camelizes a route's stored
+  controller path with the host's global inflections, which no engine-level
+  setting scopes. The autoloader is now pinned to `Api` for this engine's
+  own path, and the namespace answers to `API` as well.
+
+## [1.2.0] - 2026-08-14
+
+### ⚠️ The dashboard has moved to its own gem
+
+The dashboard engine that shipped inside `activeagent` is now a separate
+gem, **`actionagent`**. Nothing is gone — the dashboard is the same
+dashboard, and it gained a great deal in this release — but it comes from a
+different gem now. `activeagent` is the framework alone: it no longer
+defines `ActiveAgent::Dashboard`, and no longer pulls Active Record into
+apps that do not use it.
+
+**If you mount the dashboard, add the new gem in the same change that
+upgrades `activeagent`:**
+
+```ruby
+gem "activeagent", "~> 1.2"
+gem "actionagent", "~> 1.2"   # required if you mount the dashboard
+```
+
+This is a minor version, so a `~> 1.0` or `~> 1.1` constraint **will** pick
+it up on the next `bundle update`. If you mount the dashboard and do not add
+`actionagent` at the same time, the app fails at boot with
+`NameError: uninitialized constant ActiveAgent::Dashboard`, raised by your
+own initializer or by the `mount ActiveAgent::Dashboard::Engine` line in
+`config/routes.rb`. Adding the gem is the whole fix — your existing
+configuration keeps working through the compatibility shims below.
+
+If you do not mount the dashboard, there is nothing to do: the framework API
+is unchanged, and the gem is 95% smaller.
+
+With `actionagent` installed, the old constants keep resolving through
+`ActionAgent::Compatibility` with a deprecation warning:
+
+- `ActiveAgent::Dashboard` → `ActionAgent`
+- `ActiveAgent::TelemetryTrace` → `ActionAgent::TelemetryTrace`
+- `ActiveAgent::ProcessTelemetryTracesJob` → `ActionAgent::ProcessTelemetryTracesJob`
+
+That last one matters beyond tidiness: Active Job serializes the class name
+into the queue payload, so jobs enqueued before the upgrade still resolve
+after it.
+
+Other changes for mounted installs:
+
+- **The server-rendered traces console moves from `/traces` to
+  `/console/traces`.** `/traces` is now the React traces view — the same
+  data, with more of it.
+- **The mount is authenticated everywhere but development and test.** The
+  sandbox API, the session-recording capture endpoints and the template
+  endpoints previously allowed anonymous access; they no longer do. The
+  `GET /api/session_recordings/demo` endpoint is removed.
+- **`current_user_method` / `current_account_method` are superseded by
+  `current_user_resolver` / `current_account_resolver`.** The engine's
+  controllers are their own base class, so a host app's `current_user`
+  helper is not available to them.
+- **An unresolved owner now scopes to nothing rather than to everything.**
+  If you configure `user_class` or `account_class`, make sure the matching
+  resolver actually returns a record, or the dashboard will show no data.
+- Existing installs upgrading from the in-gem dashboard: re-run
+  `rails generate action_agent:install`. It detects the migrations you
+  already have and emits only what is missing.
+
 ## [1.1.0] - 2026-08-12
 
 ### Dashboard — self-hosted (enterprise) mount readiness
@@ -45,6 +191,45 @@ observability surface (see `docs/framework/self-hosted-observability.md`):
   it remains a no-op accessor with its historical default so existing
   initializers keep booting, and will be removed in the next major.
 
+### Agent-as-tool delegation
+
+Sub-agents are now a first-class primitive. A tool is a Ruby method your
+model can call; a delegation is another agent your model can call — with
+its own instructions, templates, model and budget.
+
+- **`delegation :action, description:`** declares what a sub-agent exposes:
+  a description for the calling model, a JSON Schema for its inputs (block
+  DSL, a plain hash, or any class responding to `to_json_schema`), and
+  optionally a `returns` schema. A declared `returns` becomes the
+  sub-agent's `response_format`, and its answer is parsed and checked
+  before the caller sees it.
+- **`delegate_to AgentClass`** exposes those contracts to the calling model
+  as tools, with `only:`/`except:`/`as:` for scoping and renaming,
+  `params:` for forwarding, and `action:` for declaring a contract at the
+  call site when you don't own the sub-agent. Per-action scoping via the
+  `delegations:` prompt option.
+- **Cost and latency budgets**: `max_calls`, `max_tokens`, `max_cost`,
+  `max_duration` and a per-call `timeout`, set per delegation and/or
+  agent-wide with `delegation_budget`. Exhausting one returns a structured
+  result the model can act on (`on_exceeded: :stop`, the default) instead
+  of raising mid-conversation; `:raise` is available. Budgets are scoped
+  to a single generation, and spend is readable afterwards via
+  `delegation_ledger`.
+- **Swappable backends**: `backend: :ollama` or
+  `backend: { provider: :anthropic, model: "claude-haiku-4-5" }` moves a
+  delegation to different silicon without touching the sub-agent. Provider
+  swaps rebuild provider configuration rather than merging over it, and
+  template lookup still resolves to the original agent's views.
+- **Cost registry**: `ActiveAgent::Delegation::Pricing.register` records
+  token rates in USD per 1M tokens (no built-in price list, so `max_cost`
+  never fires on stale numbers); rates can also be stated inline on a budget.
+- **Instrumentation**: `delegate.active_agent` (agent, sub-agent, action,
+  model, duration, usage, cost, ledger) and
+  `delegation_refused.active_agent` (violated limit).
+- **New docs** (`docs/actions/delegation.md`) with a worked support-triage
+  example, plus test coverage in `test/features/delegation_test.rb` and
+  `test/docs/actions/delegation_examples_test.rb`.
+
 ### Dashboard & Telemetry — dev console readiness
 
 The dashboard engine — Active Agent's local dev console — now works out of

data/README.md

@@ -10,6 +10,16 @@
 >
 > *Makes code [TonsOfFun](https://tonsoffun.github.io)!*
 
+[![Gem Version](https://img.shields.io/gem/v/activeagent?label=activeagent&logo=rubygems&color=CC342D)](https://rubygems.org/gems/activeagent)
+[![actionagent](https://img.shields.io/gem/v/actionagent?label=actionagent&logo=rubygems&color=CC342D)](https://rubygems.org/gems/actionagent)
+[![Downloads](https://img.shields.io/gem/dt/activeagent?label=downloads)](https://rubygems.org/gems/activeagent)
+[![CI](https://github.com/activeagents/activeagent/actions/workflows/ci.yml/badge.svg)](https://github.com/activeagents/activeagent/actions/workflows/ci.yml)
+[![Cross-repo integration](https://github.com/activeagents/activeagent/actions/workflows/integration.yml/badge.svg)](https://github.com/activeagents/activeagent/actions/workflows/integration.yml)
+[![Docs](https://img.shields.io/badge/docs-docs.activeagents.ai-2563eb)](https://docs.activeagents.ai)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-CC342D)](https://www.ruby-lang.org)
+[![Rails](https://img.shields.io/badge/rails-7.2%20%7C%208.0%20%7C%208.1-D30001)](https://rubyonrails.org)
+[![License](https://img.shields.io/github/license/activeagents/activeagent)](LICENSE)
+
 # Active Agent
 Active Agent provides that missing AI layer in the Rails framework, offering a structured approach to building AI-powered applications through Agent Oriented Programming. **Now Agents are Controllers!** Designing applications using agents allows developers to create modular, reusable components that can be easily integrated into existing systems. This approach promotes code reusability, maintainability, and scalability, making it easier to build complex AI-driven applications with the Object Oriented Ruby code you already use today.
 
@@ -25,6 +35,10 @@ Use bundler to add activeagent to your Gemfile and install:
 bundle add activeagent
 ```
 
+That is the framework — agents, providers, generation and telemetry
+reporting. The dashboard is a second gem, `actionagent`, added separately
+when you want it; see [Dashboard & Dev Console](#dashboard--dev-console).
+
 Add the generation provider gem you want to use:
 
 ```bash
@@ -127,14 +141,19 @@ development:
     service: "RubyLLM"
 ```
 
-## Dev Console & Observability
+## Dashboard & Dev Console
 
-Active Agent includes a local dev console — traces with span waterfalls,
-token usage, and per-agent metrics — as a mountable Rails engine, so you
-can watch your agents while you build:
+The dashboard is its own gem, `actionagent`: a mountable Rails engine with
+traces and span waterfalls, token usage and per-agent metrics, plus the agent
+builder, runs, conversations, evaluations, scorecards and cost estimates — so
+you can watch and drive your agents while you build. It ships separately
+because its models are Active Record models and it runs agents through
+[solid_agent](https://github.com/activeagents/solid_agent) — neither of which
+`activeagent` depends on, so an app that only runs agents installs neither.
 
 ```bash
-rails generate active_agent:dashboard:install
+bundle add actionagent
+rails generate action_agent:install
 rails db:migrate
 ```
 
@@ -145,13 +164,14 @@ telemetry:
   local_storage: true
 ```
 
-Open `/activeagents` and every generation appears as a trace. See
+The generator mounts the engine at `/activeagents` — open it and every
+generation appears as a trace. See
 [docs/framework/dashboard.md](docs/framework/dashboard.md) for
-authentication, remote ingestion, and multi-tenant mode. For production
-monitoring — evaluations, cost estimates, retention, team workspaces —
-point telemetry at the hosted platform at
-[activeagents.ai](https://activeagents.ai); every workspace starts with a
-free low-volume trial.
+authentication, remote ingestion, and multi-tenant mode. The hosted
+platform at [activeagents.ai](https://activeagents.ai) runs this same
+engine multi-tenant, adding what a hosted product has to have — accounts,
+plans, billing, quotas and managed sandboxes; every workspace starts with
+a free low-volume trial.
 
 ## Features
 
@@ -161,6 +181,7 @@ free low-volume trial.
 - **View Templates**: Use ERB templates for prompts (text, JSON, HTML)
 - **Streaming Support**: Real-time response streaming with ActionCable
 - **Tool/Function Calling**: Agents can use tools to interact with external services
+- **Agent-as-Tool Delegation**: Hand work to sub-agents with declared schemas, cost/latency budgets, and swappable backends
 - **Context Management**: Maintain conversation history across interactions
 - **Structured Output**: Define JSON schemas for predictable responses
 
@@ -195,16 +216,39 @@ response = prompt.generate_now
 # Response includes tool call results
 ```
 
+### Delegation
+Hand part of a job to a sub-agent, under a declared contract and a budget:
+
+```ruby
+class SummarizerAgent < ApplicationAgent
+  generate_with :openai, model: "gpt-4o-mini"
+
+  delegation :summarize, description: "Condense a document into key points" do
+    string :text, required: true, description: "Full document text"
+  end
+
+  def summarize(text:) = prompt(message: text)
+end
+
+class ResearchAgent < ApplicationAgent
+  generate_with :openai, model: "gpt-4o"
+
+  delegate_to SummarizerAgent, budget: { max_calls: 3, timeout: 20 }
+
+  def research(topic:) = prompt(message: "Research #{topic}")
+end
+```
+
 ## Learn More
 
 - [Documentation](https://docs.activeagents.ai)
 - [Getting Started Guide](https://docs.activeagents.ai/getting_started)
-- [API Reference](https://docs.activeagents.ai/docs/framework)
-- [Examples](https://docs.activeagents.ai/docs/agents)
+- [API Reference](https://docs.activeagents.ai/framework)
+- [Examples](https://docs.activeagents.ai/agents)
 
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.MD) for details.
 
 ## License
 

data/lib/active_agent/base.rb

@@ -5,6 +5,7 @@ require "active_support/core_ext/module/anonymous"
 require "active_support/core_ext/string/inflections"
 
 require "active_agent/concerns/callbacks"
+require "active_agent/concerns/delegation"
 require "active_agent/concerns/observers"
 require "active_agent/concerns/parameterized"
 require "active_agent/concerns/preview"
@@ -42,6 +43,7 @@ module ActiveAgent
     include AbstractController::Caching
 
     include Callbacks
+    include Delegation
     include Parameterized
     include Provider
     include Queueing
@@ -299,18 +301,25 @@ module ActiveAgent
 
     # @api private
     def prepare_prompt_parameters
-      parameters = prompt_options.deep_dup.except(:locals, *PROTECTED_OPTIONS)
+      parameters = prompt_options.deep_dup.except(:locals, :delegations, *PROTECTED_OPTIONS)
 
       # Render out proc/lamda attributes before rendering templates
       parameters.deep_transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
 
+      # Expose declared sub-agents (agent-as-tool) alongside the action's own tools
+      parameters = apply_delegated_tools(parameters, prompt_options)
+
       # Strip parameters the target model rejects (e.g. temperature/top_p
       # on thinking-first models) before they reach the provider.
       ModelCapabilities.sanitize!(parameters)
 
       # Apply Callbacks
+      #
+      # The trace id is written back so it stays stable for the generation and
+      # readable from prompt_options — delegated sub-agents inherit it, which
+      # is what lets a delegation tree show up as one trace.
       parameters.merge!(
-        trace_id: prompt_options[:trace_id] || SecureRandom.uuid,
+        trace_id: prompt_options[:trace_id] ||= SecureRandom.uuid,
         exception_handler:,
         stream_broadcaster:,
         tools_function:,