envoy_ai 0.0.1

data/app/models/envoy/system_prompt.rb

@@ -0,0 +1,24 @@
+module Envoy
+  class SystemPrompt < ApplicationRecord
+    has_many :versions, -> { order(:version_number) },
+             class_name: "Envoy::SystemPromptVersion",
+             foreign_key: "system_prompt_id",
+             inverse_of: :system_prompt,
+             dependent: :destroy
+
+    validates :name, presence: true, uniqueness: true
+
+    def latest_version
+      versions.order(:version_number).last
+    end
+
+    def current_body
+      latest_version&.body
+    end
+
+    def add_version!(body)
+      next_number = (versions.maximum(:version_number) || 0) + 1
+      versions.create!(version_number: next_number, body: body)
+    end
+  end
+end

data/app/models/envoy/system_prompt_version.rb

@@ -0,0 +1,14 @@
+module Envoy
+  class SystemPromptVersion < ApplicationRecord
+    belongs_to :system_prompt, class_name: "Envoy::SystemPrompt", inverse_of: :versions
+
+    validates :version_number, presence: true, uniqueness: { scope: :system_prompt_id }
+    validates :body, presence: true
+
+    attr_readonly :body, :version_number, :system_prompt_id
+
+    before_update do
+      raise ActiveRecord::ReadOnlyRecord, "Envoy::SystemPromptVersion is immutable"
+    end
+  end
+end

data/app/models/envoy/tool_call.rb

@@ -0,0 +1,28 @@
+module Envoy
+  class ToolCall < ApplicationRecord
+    acts_as_tool_call message_class: "Envoy::Message"
+
+    # The tool-result message that answers this call (role "tool").
+    def result_message
+      Envoy::Message.find_by(tool_call_id: id)
+    end
+
+    # Derive a governance outcome from the persisted result, tolerant of how the
+    # result content was serialized. Returns :denied / :failed / :succeeded.
+    def outcome
+      payload = parsed_result
+      return :succeeded unless payload.is_a?(Hash) && payload["error"]
+      payload["type"] == "forbidden" ? :denied : :failed
+    end
+
+    private
+
+    def parsed_result
+      raw = result_message&.content
+      return nil if raw.blank?
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      { "error" => raw }
+    end
+  end
+end

data/app/views/envoy/conversations/_composer_input.html.erb

@@ -0,0 +1,4 @@
+<%= text_area_tag "message[content]", nil,
+      id: "envoy_composer_input", rows: 2, autofocus: true,
+      class: "envoy-input",
+      data: { controller: "envoy-composer", action: "keydown.enter->envoy-composer#submit" } %>

data/app/views/envoy/conversations/index.html.erb

@@ -0,0 +1,15 @@
+<div class="envoy-header-row envoy-mb-4">
+  <h1 class="envoy-title">Envoy chats</h1>
+  <div class="envoy-btn-group">
+    <%= link_to "System prompts", system_prompts_path,
+          class: "envoy-btn envoy-btn--secondary" %>
+    <%= link_to "New chat", new_conversation_path,
+          class: "envoy-btn" %>
+  </div>
+</div>
+<ul class="envoy-list">
+  <% @conversations.each do |c| %>
+    <li class="envoy-list__item"><%= link_to (c.title.presence || "Chat ##{c.id}"), conversation_path(c), class: "envoy-link" %>
+      <span class="envoy-muted">· <%= c.toolset_key %> · <%= c.model_id %></span></li>
+  <% end %>
+</ul>

data/app/views/envoy/conversations/new.html.erb

@@ -0,0 +1,19 @@
+<% field = "envoy-field" %>
+<h1 class="envoy-title envoy-mb-4">New chat</h1>
+<%= form_with model: @conversation, url: conversations_path do |f| %>
+  <div class="envoy-form">
+    <%= f.text_field :title, placeholder: "Title (optional)", class: field %>
+    <%= f.select :toolset_key, Envoy.toolsets.keys, {}, class: field %>
+    <%= f.select :model_id, Envoy.config.available_models, {}, class: field %>
+    <div>
+      <label class="envoy-label">Saved system prompt</label>
+      <%= select_tag "conversation[system_prompt_id]",
+            options_for_select([["None", ""]] + Envoy::SystemPrompt.order(:name).map { |p| [p.name, p.id] }),
+            class: field %>
+    </div>
+    <%= f.text_area :system_prompt, rows: 4,
+          placeholder: "Additional instructions (optional) — appended to the selected saved prompt, or used alone as a custom prompt",
+          class: field %>
+    <%= f.submit "Start", class: "envoy-btn" %>
+  </div>
+<% end %>

data/app/views/envoy/conversations/show.html.erb

@@ -0,0 +1,18 @@
+<%= turbo_stream_from @conversation, "messages" %>
+<h1 class="envoy-title--sm envoy-mb-3"><%= @conversation.title.presence || "Chat ##{@conversation.id}" %></h1>
+
+<div data-controller="envoy-autoscroll">
+  <div id="envoy_messages" class="envoy-stack envoy-mb-4">
+    <% @conversation.messages.where(role: %w[user assistant]).each do |message| %>
+      <%= render "envoy/messages/message", message: message %>
+    <% end %>
+  </div>
+</div>
+
+<%= form_with url: conversation_messages_path(@conversation), method: :post do |f| %>
+  <div class="envoy-composer">
+    <%= render "envoy/conversations/composer_input" %>
+    <%= f.submit "Send", class: "envoy-btn" %>
+  </div>
+  <p class="envoy-hint">Enter to send · Shift/Option+Enter for a new line</p>
+<% end %>

data/app/views/envoy/messages/_message.html.erb

@@ -0,0 +1,7 @@
+<div class="envoy-msg<%= ' envoy-msg--assistant' if message.role != 'user' %>">
+  <div class="envoy-msg__role"><%= message.role %></div>
+  <div class="envoy-md"><%= Envoy::Markdown.render(message.content) %></div>
+  <% message.tool_calls.each do |tc| %>
+    <%= render "envoy/messages/tool_call", tool_call: tc %>
+  <% end %>
+</div>

data/app/views/envoy/messages/_streaming.html.erb

@@ -0,0 +1,6 @@
+<div id="envoy_streaming_reply">
+  <div class="envoy-msg envoy-msg--assistant">
+    <div class="envoy-msg__role">assistant</div>
+    <div class="envoy-md"><%= Envoy::Markdown.render(content) %></div>
+  </div>
+</div>

data/app/views/envoy/messages/_tool_call.html.erb

@@ -0,0 +1,8 @@
+<details class="envoy-tool">
+  <summary class="envoy-tool__summary">
+    <span class="envoy-mono"><%= tool_call.name %></span>
+    <%= Envoy::Badges.outcome(tool_call) %>
+  </summary>
+  <pre><%= JSON.pretty_generate(tool_call.arguments) %></pre>
+  <pre><%= tool_call.result_message&.content %></pre>
+</details>

data/app/views/envoy/messages/create.turbo_stream.erb

@@ -0,0 +1,25 @@
+<%# Append the user message, then a fresh streaming target — both into the ordered
+    message list so the assistant reply commits in place and the next turn appends
+    after it (fixes cross-turn ordering). %>
+<%= turbo_stream.append "envoy_messages" do %>
+  <div class="envoy-msg">
+    <div class="envoy-msg__role">user</div>
+    <div class="envoy-md"><%= Envoy::Markdown.render(@user_content) %></div>
+  </div>
+<% end %>
+<%# The streaming target starts with a subtle "working…" indicator so there is a
+    live sign of activity before the first token (e.g. during tool calls, which
+    emit no text deltas). The first delta / finalize replaces this. %>
+<%= turbo_stream.append "envoy_messages" do %>
+  <div id="envoy_streaming_reply">
+    <div class="envoy-msg envoy-msg--assistant">
+      <div class="envoy-msg__role">assistant</div>
+      <div class="envoy-working envoy-muted">working…</div>
+    </div>
+  </div>
+<% end %>
+<%# Clear the composer by replacing it with a fresh, empty textarea (server-driven,
+    so it works even if the Stimulus controller didn't load). %>
+<%= turbo_stream.replace "envoy_composer_input" do %>
+  <%= render "envoy/conversations/composer_input" %>
+<% end %>

data/app/views/envoy/system_prompts/_form.html.erb

@@ -0,0 +1,14 @@
+<%= form_with model: system_prompt, url: url do |f| %>
+  <% if system_prompt.errors.any? %>
+    <div class="envoy-error">
+      <% system_prompt.errors.full_messages.each do |m| %><div><%= m %></div><% end %>
+    </div>
+  <% end %>
+  <div class="envoy-form">
+    <%= f.text_field :name, placeholder: "Name", class: "envoy-field" %>
+    <%= f.text_field :description, placeholder: "Description (optional)", class: "envoy-field" %>
+    <%= text_area_tag "system_prompt[body]", system_prompt.current_body, rows: 12,
+          placeholder: "System prompt body", class: "envoy-field envoy-field--mono" %>
+    <%= f.submit submit_label, class: "envoy-btn" %>
+  </div>
+<% end %>

data/app/views/envoy/system_prompts/edit.html.erb

@@ -0,0 +1,2 @@
+<h1 class="envoy-title envoy-mb-4">Edit system prompt</h1>
+<%= render "form", system_prompt: @system_prompt, url: system_prompt_path(@system_prompt), submit_label: "Save" %>

data/app/views/envoy/system_prompts/index.html.erb

@@ -0,0 +1,14 @@
+<div class="envoy-header-row envoy-mb-4">
+  <h1 class="envoy-title">System prompts</h1>
+  <%= link_to "New prompt", new_system_prompt_path, class: "envoy-btn" %>
+</div>
+<ul class="envoy-list">
+  <% @system_prompts.each do |p| %>
+    <li class="envoy-list__item">
+      <%= link_to p.name, system_prompt_path(p), class: "envoy-link" %>
+      <span class="envoy-muted">· v<%= p.latest_version&.version_number || 0 %></span>
+      <% if p.description.present? %><div class="envoy-muted"><%= p.description %></div><% end %>
+    </li>
+  <% end %>
+</ul>
+<div class="envoy-mt-4"><%= link_to "← Chats", conversations_path, class: "envoy-link" %></div>

data/app/views/envoy/system_prompts/new.html.erb

@@ -0,0 +1,2 @@
+<h1 class="envoy-title envoy-mb-4">New system prompt</h1>
+<%= render "form", system_prompt: @system_prompt, url: system_prompts_path, submit_label: "Create" %>

data/app/views/envoy/system_prompts/show.html.erb

@@ -0,0 +1,15 @@
+<div class="envoy-header-row envoy-mb-3">
+  <h1 class="envoy-title"><%= @system_prompt.name %></h1>
+  <%= link_to "Edit", edit_system_prompt_path(@system_prompt), class: "envoy-btn" %>
+</div>
+<% if @system_prompt.description.present? %>
+  <p class="envoy-muted envoy-mb-3"><%= @system_prompt.description %></p>
+<% end %>
+<pre class="envoy-prose-box envoy-mb-4"><%= @system_prompt.current_body %></pre>
+<h2 class="envoy-subtitle">Versions</h2>
+<ul class="envoy-list">
+  <% @system_prompt.versions.order(version_number: :desc).each do |v| %>
+    <li class="envoy-list__item envoy-muted">v<%= v.version_number %> · <%= v.created_at.strftime("%Y-%m-%d %H:%M") %></li>
+  <% end %>
+</ul>
+<div class="envoy-mt-4"><%= link_to "← System prompts", system_prompts_path, class: "envoy-link" %></div>

data/app/views/layouts/envoy/application.html.erb

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Envoy</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <%= stylesheet_link_tag "envoy/console", "data-turbo-track": "reload" %>
+    <%= javascript_importmap_tags %>
+  </head>
+  <body class="envoy-body">
+    <header class="envoy-header">
+      <div class="envoy-header__inner">
+        <%= link_to "Envoy", conversations_path, class: "envoy-brand" %>
+        <%= link_to "New chat", new_conversation_path, class: "envoy-navlink" %>
+      </div>
+    </header>
+    <main class="envoy-main"><%= yield %></main>
+  </body>
+</html>

data/config/routes.rb

@@ -0,0 +1,7 @@
+Envoy::Engine.routes.draw do
+  resources :conversations, only: %i[index new create show] do
+    resources :messages, only: :create
+  end
+  resources :system_prompts, except: :destroy
+  root to: "conversations#index"
+end

data/db/migrate/20260710000001_create_envoy_conversations.rb

@@ -0,0 +1,14 @@
+class CreateEnvoyConversations < ActiveRecord::Migration[8.1]
+  def change
+    create_table :envoy_conversations do |t|
+      t.references :actor, polymorphic: true, null: false
+      t.string  :title
+      t.string  :provider,    null: false, default: "anthropic"
+      t.string  :model_id,    null: false
+      t.string  :toolset_key, null: false
+      t.text    :system_prompt
+      t.string  :status,      null: false, default: "active"
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260710000002_create_envoy_messages.rb

@@ -0,0 +1,14 @@
+class CreateEnvoyMessages < ActiveRecord::Migration[8.1]
+  def change
+    create_table :envoy_messages do |t|
+      t.references :conversation, null: false, foreign_key: { to_table: :envoy_conversations }
+      t.string  :role, null: false
+      t.text    :content
+      t.string  :model_id
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.references :tool_call, null: true, index: true
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260710000003_create_envoy_tool_calls.rb

@@ -0,0 +1,14 @@
+class CreateEnvoyToolCalls < ActiveRecord::Migration[8.1]
+  def change
+    create_table :envoy_tool_calls do |t|
+      t.references :message, null: false, foreign_key: { to_table: :envoy_messages }
+      t.string :tool_call_id, null: false
+      t.string :name, null: false
+      t.json   :arguments, default: {}
+      t.string :status
+      t.text   :error
+      t.timestamps
+    end
+    add_index :envoy_tool_calls, :tool_call_id
+  end
+end

data/db/migrate/20260711000001_create_envoy_system_prompts.rb

@@ -0,0 +1,10 @@
+class CreateEnvoySystemPrompts < ActiveRecord::Migration[8.1]
+  def change
+    create_table :envoy_system_prompts do |t|
+      t.string :name, null: false
+      t.text   :description
+      t.timestamps
+    end
+    add_index :envoy_system_prompts, :name, unique: true
+  end
+end

data/db/migrate/20260711000002_create_envoy_system_prompt_versions.rb

@@ -0,0 +1,13 @@
+class CreateEnvoySystemPromptVersions < ActiveRecord::Migration[8.1]
+  def change
+    create_table :envoy_system_prompt_versions do |t|
+      t.references :system_prompt, null: false, index: true,
+                   foreign_key: { to_table: :envoy_system_prompts }
+      t.integer :version_number, null: false
+      t.text    :body, null: false
+      t.timestamps
+    end
+    add_index :envoy_system_prompt_versions, %i[system_prompt_id version_number],
+              unique: true, name: "index_envoy_prompt_versions_on_prompt_and_number"
+  end
+end

data/db/migrate/20260711000003_add_system_prompt_version_to_envoy_conversations.rb

@@ -0,0 +1,6 @@
+class AddSystemPromptVersionToEnvoyConversations < ActiveRecord::Migration[8.1]
+  def change
+    add_reference :envoy_conversations, :system_prompt_version, null: true, index: true,
+                  foreign_key: { to_table: :envoy_system_prompt_versions }
+  end
+end

data/lib/envoy/badges.rb

@@ -0,0 +1,22 @@
+module Envoy
+  # Renders a tool-call outcome badge as an HTML-safe string. A plain module
+  # method (NOT a view helper), for the same reason as Envoy::Markdown: Turbo
+  # broadcasts render through the host's ApplicationController, which cannot see
+  # engine view helpers. Call directly: `<%= Envoy::Badges.outcome(tool_call) %>`.
+  module Badges
+    module_function
+
+    # Modifier classes are styled by the gem's own console.css (semantic, not
+    # Tailwind) so the badge stays styled in any host.
+    STYLES = {
+      denied: [ "denied", "envoy-badge--denied" ],
+      failed: [ "failed", "envoy-badge--failed" ]
+    }.freeze
+    SUCCESS = [ "ok", "envoy-badge--ok" ].freeze
+
+    def outcome(tool_call)
+      label, modifier = STYLES.fetch(tool_call.outcome, SUCCESS)
+      %(<span class="envoy-badge #{modifier}">#{label}</span>).html_safe
+    end
+  end
+end

data/lib/envoy/compiled_tool.rb

@@ -0,0 +1,43 @@
+module Envoy
+  module CompiledTool
+    module_function
+
+    # Build (once) a RubyLLM::Tool subclass for a ToolDefinition.
+    def build(definition)
+      definition.tool_class || begin
+        klass = Class.new(RubyLLM::Tool) do
+          @definition = definition
+
+          class << self
+            attr_reader :definition
+          end
+
+          description definition.description
+          definition.params.each do |p|
+            param p[:name], desc: p[:desc], type: p[:type], required: p[:required]
+          end
+
+          attr_reader :last_status
+
+          def initialize(actor:)
+            @actor = actor
+            @last_status = nil
+          end
+
+          # RubyLLM derives the tool name from the class; override to the DSL name.
+          def name
+            self.class.definition.name
+          end
+
+          def execute(**args)
+            out = Envoy::Guard.run(self.class.definition, actor: @actor, args: args)
+            @last_status = out[:status]
+            out[:value].to_json
+          end
+        end
+        definition.tool_class = klass
+        klass
+      end
+    end
+  end
+end

data/lib/envoy/configuration.rb

@@ -0,0 +1,21 @@
+module Envoy
+  class Configuration
+    attr_accessor :provider, :default_model, :available_models,
+                  :authenticate, :actor_resolver, :system_preamble
+    attr_writer :llm
+
+    def initialize
+      @provider         = :anthropic
+      @default_model    = "claude-sonnet-4-5"
+      @available_models = [ "claude-sonnet-4-5", "claude-opus-4-1" ]
+      @authenticate     = ->(controller) { }
+      @actor_resolver   = ->(controller) { nil }
+      @system_preamble  = "You are a helpful assistant embedded in a Rails app."
+    end
+
+    # Returns a fresh LLM runner. Overridable in tests via `config.llm = ...`.
+    def llm
+      @llm ||= ->(**opts) { Envoy::LLM.new(**opts) }
+    end
+  end
+end

data/lib/envoy/engine.rb

@@ -0,0 +1,19 @@
+module Envoy
+  class Engine < ::Rails::Engine
+    isolate_namespace Envoy
+
+    config.generators do |g|
+      g.test_framework :minitest
+    end
+
+    # Expose the engine's Stimulus controllers to the host's asset pipeline so
+    # `pin "envoy/controllers/...", to: "envoy/controllers/..._controller.js"`
+    # in the host importmap resolves. (Importmap::Map#paths is for additional
+    # importmap.rb-style DSL files, not raw JS directories, so the pin/resolve
+    # path here goes through the asset load path instead.)
+    initializer "envoy.assets" do |app|
+      app.config.assets.paths << root.join("app/javascript") if app.config.respond_to?(:assets)
+      app.config.assets.paths << root.join("app/assets/stylesheets") if app.config.respond_to?(:assets)
+    end
+  end
+end

data/lib/envoy/errors.rb

@@ -0,0 +1,6 @@
+module Envoy
+  class Error < StandardError; end
+  class Forbidden < Error; end
+  class UnknownToolset < Error; end
+  class ToolsetCycle < Error; end
+end

data/lib/envoy/guard.rb

@@ -0,0 +1,28 @@
+module Envoy
+  module Guard
+    module_function
+
+    # Runs a tool definition's perform block, translating exceptions into
+    # model-legible results. Never raises for expected failures.
+    def run(definition, actor:, args:)
+      value = definition.perform_block.call(actor: actor, **args.symbolize_keys)
+      if value.is_a?(Hash) && value[:error]
+        { value: value, status: :failed }
+      else
+        { value: value, status: :succeeded }
+      end
+    rescue Envoy::Forbidden => e
+      failure("forbidden", e.message.presence || "Not permitted.", :denied)
+    rescue ActiveRecord::RecordNotFound
+      failure("not_found", "The requested record was not found.", :failed)
+    rescue ArgumentError => e
+      failure("invalid", e.message, :failed)
+    rescue StandardError
+      failure("error", "An unexpected error occurred.", :failed)
+    end
+
+    def failure(type, message, status)
+      { value: { error: message, type: type }, status: status }
+    end
+  end
+end

data/lib/envoy/llm.rb

@@ -0,0 +1,24 @@
+module Envoy
+  class LLM
+    def initialize(conversation:)
+      @conversation = conversation
+    end
+
+    # Drives a real RubyLLM turn via acts_as_chat. Yields [:delta, text] chunks.
+    #
+    # NOTE: RubyLLM 1.16's ChatMethods#with_model keyword is `assume_exists:`,
+    # not `assume_model_exists:` — verified against the installed gem
+    # (lib/ruby_llm/active_record/chat_methods.rb and lib/ruby_llm/chat.rb).
+    def run(content:, tools:, instructions:)
+      chat = @conversation
+        .with_model(@conversation.model_id,
+                    provider: Envoy.config.provider,
+                    assume_exists: true)
+        .with_instructions(instructions)
+      chat = chat.with_tools(*tools) if tools.any?
+      chat.ask(content) do |chunk|
+        yield [ :delta, chunk.content ] if block_given? && chunk.content.present?
+      end
+    end
+  end
+end

data/lib/envoy/markdown.rb

@@ -0,0 +1,16 @@
+require "commonmarker"
+
+module Envoy
+  # Renders Markdown to sanitized HTML. A plain module method (NOT a view helper)
+  # so it works in any render context — including Turbo broadcasts, which render
+  # partials through the host's ApplicationController and cannot see engine view
+  # helpers. Call directly from partials: `<%= Envoy::Markdown.render(text) %>`.
+  module Markdown
+    module_function
+
+    def render(text)
+      return "".html_safe if text.blank?
+      Commonmarker.to_html(text, options: { render: { unsafe: false } }).html_safe
+    end
+  end
+end

data/lib/envoy/runner.rb

@@ -0,0 +1,44 @@
+module Envoy
+  class Runner
+    ERROR_CONVENTION = <<~TXT.freeze
+      When a tool returns a JSON object with an "error" key, it failed. The
+      "type" tells you why: "not_found" (no such record), "forbidden" (you may
+      not do that), "invalid" (bad arguments). Explain the problem to the user
+      instead of retrying blindly.
+    TXT
+
+    def initialize(conversation:)
+      @conversation = conversation
+    end
+
+    def call(content:, &on_event)
+      tools = compiled_tools
+      Envoy.llm(conversation: @conversation)
+           .run(content: content, tools: tools, instructions: instructions, &on_event)
+      backfill_statuses!
+    end
+
+    private
+
+    def toolset = @conversation.toolset
+
+    def read_only? = @conversation.status == "read_only"
+
+    def compiled_tools
+      toolset.tools_for(read_only: read_only?).map do |definition|
+        Envoy::CompiledTool.build(definition).new(actor: @conversation.actor)
+      end
+    end
+
+    def instructions
+      [ Envoy.config.system_preamble, toolset.description, ERROR_CONVENTION,
+       @conversation.effective_system_prompt ].compact_blank.join("\n\n")
+    end
+
+    def backfill_statuses!
+      @conversation.messages.where(role: "assistant").flat_map(&:tool_calls).each do |tc|
+        tc.update!(status: tc.outcome.to_s) if tc.status.blank?
+      end
+    end
+  end
+end

data/lib/envoy/testing/fake_llm.rb

@@ -0,0 +1,41 @@
+module Envoy
+  module Testing
+    # Deterministic stand-in for Envoy::LLM. Persists Envoy rows exactly as the
+    # real path would and replays a script of {text:} / {tool:, args:} directives.
+    class FakeLLM
+      attr_accessor :script
+
+      def initialize(conversation:)
+        @conversation = conversation
+        @script = []
+      end
+
+      def run(content:, tools:, instructions:)
+        @conversation.messages.create!(role: "user", content: content)
+        assistant = @conversation.messages.create!(role: "assistant", content: nil)
+
+        @script.each do |directive|
+          if directive[:text]
+            # Accumulate like real streaming: multiple text deltas build one message.
+            assistant.update!(content: assistant.content.to_s + directive[:text])
+            yield [ :delta, directive[:text] ] if block_given?
+          else
+            tool = tools.find { |t| t.name == directive[:tool].to_s }
+            raise "no tool #{directive[:tool]}" unless tool
+
+            value = tool.execute(**directive[:args])
+            tc = assistant.tool_calls.create!(
+              tool_call_id: "fake-#{assistant.tool_calls.count + 1}",
+              name: tool.name, arguments: directive[:args].stringify_keys,
+              status: tool.last_status.to_s
+            )
+            @conversation.messages.create!(
+              role: "tool", tool_call_id: tc.id, content: value
+            )
+            yield [ :tool, tc ] if block_given?
+          end
+        end
+      end
+    end
+  end
+end