envoy_ai 0.0.1 → 0.0.3

data/lib/envoy/engine.rb

@@ -15,5 +15,11 @@ module Envoy
       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
+
+    initializer "envoy.page_surface" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include Envoy::PageSurface
+      end
+    end
   end
 end

data/lib/envoy/errors.rb

@@ -3,4 +3,8 @@ module Envoy
   class Forbidden < Error; end
   class UnknownToolset < Error; end
   class ToolsetCycle < Error; end
+  class UnknownPrompt < Error; end
+  class PromptCycle < Error; end
+  class UnknownSurface < Error; end
+  class UnknownLibrary < Error; end
 end

data/lib/envoy/guard.rb

@@ -5,7 +5,9 @@ module Envoy
     # 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)
+      args = args.symbolize_keys
+      validate_enums!(definition, args)
+      value = definition.perform_block.call(actor: actor, **args)
       if value.is_a?(Hash) && value[:error]
         { value: value, status: :failed }
       else
@@ -24,5 +26,15 @@ module Envoy
     def failure(type, message, status)
       { value: { error: message, type: type }, status: status }
     end
+
+    # A closed vocabulary is a contract: reject an unknown value with the valid
+    # list rather than letting the perform block improvise on a hallucinated key.
+    def validate_enums!(definition, args)
+      args.each do |name, value|
+        allowed = definition.enum_for(name)
+        next if allowed.nil? || allowed.include?(value.to_s)
+        raise ArgumentError, "#{name} must be one of: #{allowed.join(', ')} (got #{value.inspect})"
+      end
+    end
   end
 end

data/lib/envoy/library.rb

@@ -0,0 +1,82 @@
+module Envoy
+  # A set of reference documents the model can pull on demand.
+  #
+  # Progressive disclosure: preloading every reference doc costs thousands of
+  # tokens on turns that never need them. A library puts a short index in the
+  # instructions and hands the model one tool to fetch a document when the task
+  # actually calls for it.
+  #
+  # Compiles to an ordinary Toolset, so it composes via `use`, merges its
+  # description into instructions, and honours read_only — all for free.
+  class Library
+    attr_reader :key
+
+    def initialize(key)
+      @key = key.to_s
+      @description = ""
+      @documents = {} # slug => { summary:, body: callable }
+    end
+
+    def description(text = nil)
+      return rendered_description if text.nil?
+      @description = text
+    end
+
+    # Register one document. The block is the lazy body.
+    def document(slug, summary = nil, &block)
+      @documents[slug.to_s] = { summary: summary, body: block }
+    end
+
+    # Ingest a directory of markdown: README.md becomes the description, every
+    # other *.md becomes a document keyed by its slug. Flat, non-recursive.
+    #
+    # No markdown parsing: a README that documents its own directory already
+    # carries the human-written index, and the tool's enum carries the
+    # machine-readable key list. Explicit `document` calls win over files.
+    def directory(path)
+      path = Pathname(path)
+      readme = path.join("README.md")
+      @description = readme.read if readme.exist?
+
+      path.glob("*.md").sort.each do |file|
+        slug = file.basename(".md").to_s
+        next if slug.casecmp("README").zero?
+        @documents[slug] ||= { summary: nil, body: -> { file.read } }
+      end
+    end
+
+    def document_keys
+      @documents.keys.sort
+    end
+
+    def read(slug)
+      entry = @documents[slug.to_s]
+      raise ArgumentError, "no document #{slug.inspect}" unless entry
+      entry[:body].call
+    end
+
+    # The description plus an index of any documents that carry their own
+    # summary. Directory-ingested docs are indexed by the README itself, so
+    # listing them again would just duplicate it.
+    def rendered_description
+      summarised = @documents.select { |_, entry| entry[:summary].present? }
+      return @description if summarised.empty?
+
+      index = summarised.map { |slug, entry| "  #{slug} — #{entry[:summary]}" }
+      [ @description, "Also available:", *index ].compact_blank.join("\n")
+    end
+
+    def to_toolset
+      library = self
+      toolset = Envoy::Toolset.new(key)
+      toolset.description(rendered_description)
+      toolset.tool("read_#{key}") do
+        description "Read one #{library.key} reference document in full."
+        access :read
+        param :key, "Which document to read.", enum: library.document_keys
+        perform { |actor:, key:| library.read(key) }
+      end
+      toolset
+    end
+  end
+end

data/lib/envoy/llm.rb

@@ -11,7 +11,7 @@ module Envoy
     # (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,
+        .with_model(@conversation.resolved_model_id,
                     provider: Envoy.config.provider,
                     assume_exists: true)
         .with_instructions(instructions)

data/lib/envoy/page_surface.rb

@@ -0,0 +1,34 @@
+module Envoy
+  # Declares which surface a page opens a chat against.
+  #
+  #   class TodayController < ApplicationController
+  #     envoy_surface :today, context_key: -> { "day:#{@date.to_fs(:iso8601)}" }
+  #   end
+  #
+  # The context_key lambda is instance_exec'd in the controller, so instance
+  # variables set by the action are in scope. Pages that do not declare a
+  # surface get no bubble — opt-in by default.
+  module PageSurface
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :envoy_surface_config, instance_writer: false, default: nil
+      helper_method :envoy_page_surface
+    end
+
+    class_methods do
+      def envoy_surface(key, context_key: nil)
+        self.envoy_surface_config = { key: key.to_s, context_key: context_key }
+      end
+    end
+
+    # Nil when the controller never declared one — the layout renders nothing.
+    def envoy_page_surface
+      config = envoy_surface_config
+      return nil if config.nil?
+
+      { surface: config[:key],
+        context_key: config[:context_key] && instance_exec(&config[:context_key]) }
+    end
+  end
+end

data/lib/envoy/prompt.rb

@@ -0,0 +1,55 @@
+module Envoy
+  # A named block of system-prompt text, composable like a Toolset.
+  #
+  # Prompts are code, not data: git is the version store. Bodies may be a String
+  # or a block; a block stays lazy so a host reading from disk picks up edits on
+  # `to_prepare` reload without a boot.
+  class Prompt
+    attr_reader :key
+
+    def initialize(key)
+      @key = key.to_s
+      @body = nil
+      @composed_keys = []
+    end
+
+    # Setter with text or a block; reader (no args) returns this prompt's own
+    # resolved body only. Use #full_body for the composed result.
+    def body(text = nil, &block)
+      return own_body if text.nil? && block.nil?
+      @body = block || text
+    end
+
+    # Compose other prompts into this one. Keys resolve lazily (at full_body
+    # time), so definition load order does not matter.
+    def use(*keys)
+      @composed_keys.concat(keys.map(&:to_s))
+    end
+
+    # Composed bodies first, then this prompt's own — so shared framing (safety
+    # rules, draft status) precedes the specialisation that builds on it.
+    def full_body
+      collect_bodies.compact_blank.join("\n\n").presence
+    end
+
+    protected
+
+    def collect_bodies(seen = [])
+      guard_cycle!(seen)
+      bodies = @composed_keys.flat_map { |k| Envoy.prompt(k).collect_bodies(seen + [ key ]) }
+      bodies << own_body
+      bodies
+    end
+
+    private
+
+    def own_body
+      @body.respond_to?(:call) ? @body.call : @body
+    end
+
+    def guard_cycle!(seen)
+      return unless seen.include?(key)
+      raise Envoy::PromptCycle, "prompt composition cycle: #{(seen + [ key ]).join(' -> ')}"
+    end
+  end
+end

data/lib/envoy/runner.rb

@@ -22,7 +22,7 @@ module Envoy
 
     def toolset = @conversation.toolset
 
-    def read_only? = @conversation.status == "read_only"
+    def read_only? = @conversation.read_only?
 
     def compiled_tools
       toolset.tools_for(read_only: read_only?).map do |definition|
@@ -30,9 +30,23 @@ module Envoy
       end
     end
 
+    # Ordered stable-prefix-first: the leading segments are identical across
+    # turns and so are cacheable, while context is re-resolved every turn and
+    # never is. A resumed conversation outlives the page state it started with,
+    # which is exactly why context cannot be a snapshot.
     def instructions
-      [ Envoy.config.system_preamble, toolset.description, ERROR_CONVENTION,
-       @conversation.effective_system_prompt ].compact_blank.join("\n\n")
+      [ Envoy.config.system_preamble,
+        toolset.description,
+        ERROR_CONVENTION,
+        @conversation.prompt_body,
+        surface_context,
+        @conversation.effective_system_prompt ].compact_blank.join("\n\n")
+    end
+
+    def surface_context
+      surface = @conversation.surface
+      return nil unless surface
+      surface.context_for(actor: @conversation.actor, key: @conversation.context_key)
     end
 
     def backfill_statuses!

data/lib/envoy/surface.rb

@@ -0,0 +1,90 @@
+module Envoy
+  # Binds a page to an agent: which tools, which prompt, which model, and how to
+  # describe what the user is looking at.
+  #
+  # A surface is the source of truth for a conversation opened against it —
+  # toolset, prompt and model are read here on every turn, so editing a surface
+  # reaches conversations that already exist.
+  #
+  # References are stored as keys and resolved lazily (Envoy.validate! checks
+  # them in one pass at boot), so definition load order does not matter.
+  class Surface
+    attr_reader :key
+
+    def initialize(key)
+      @key = key.to_s
+      @toolset_key = nil
+      @model_id = nil
+      @read_only = false
+      @prompt = nil
+      @context_block = nil
+    end
+
+    # --- DSL ---
+    def toolset(name = nil)
+      return @toolset_key if name.nil?
+      @toolset_key = name.to_s
+    end
+
+    def model(id = nil)
+      return @model_id if id.nil?
+      @model_id = id
+    end
+
+    def read_only(value = nil)
+      return @read_only if value.nil?
+      @read_only = value
+    end
+
+    # A registry key (Symbol) or a literal String.
+    def system_prompt(ref = nil)
+      return @prompt if ref.nil?
+      @prompt = ref
+    end
+
+    # Runs on every turn, in the job — so it gets actor and key and nothing else.
+    # No request, no params, no session. This is also where a host enforces that
+    # this actor may see this subject: raise Envoy::Forbidden and Guard handles it.
+    def context(&block)
+      @context_block = block
+    end
+
+    # --- introspection ---
+    def toolset_key = @toolset_key
+    def model_id    = @model_id
+    def read_only?  = !!@read_only
+
+    def prompt_body
+      case @prompt
+      when nil    then nil
+      when String then @prompt
+      else Envoy.prompt(@prompt).full_body
+      end
+    end
+
+    def context_for(actor:, key:)
+      return nil unless @context_block
+      @context_block.call(actor: actor, key: key)
+    end
+
+    # Resolve every lazy reference, naming this surface in any failure.
+    def validate!
+      raise Envoy::Error, "surface #{key.inspect} has no toolset" if @toolset_key.blank?
+
+      begin
+        # tools_for walks the whole `use` graph, not just this toolset's own
+        # tools — so a typo in a composed toolset's `use` list fails here,
+        # at boot, instead of surfacing mid-conversation inside RunJob.
+        Envoy.toolset(@toolset_key).tools_for
+      rescue Envoy::UnknownToolset, Envoy::ToolsetCycle => e
+        raise e.class, "surface #{key.inspect}: #{e.message}"
+      end
+
+      begin
+        prompt_body
+      rescue Envoy::UnknownPrompt => e
+        raise Envoy::UnknownPrompt, "surface #{key.inspect}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/envoy/tool_definition.rb

@@ -23,8 +23,18 @@ module Envoy
       @access = level
     end
 
-    def param(name, desc, type: :string, required: true)
-      @params << { name: name.to_sym, desc: desc, type: type, required: required }
+    # enum declares a closed vocabulary for a param. RubyLLM::Parameter has no
+    # enum support (its initializer would raise on the keyword), so the values
+    # are folded into the description the model reads, and Guard enforces them —
+    # yielding the same {"error":..,"type":"invalid"} shape as any other bad argument.
+    def param(name, desc, type: :string, required: true, enum: nil)
+      enum = enum&.map(&:to_s)
+      desc = "#{desc} One of: #{enum.join(', ')}." if enum
+      @params << { name: name.to_sym, desc: desc, type: type, required: required, enum: enum }
+    end
+
+    def enum_for(param_name)
+      @params.find { |p| p[:name] == param_name.to_sym }&.fetch(:enum)
     end
 
     def perform(&block)

data/lib/envoy/version.rb

@@ -1,3 +1,3 @@
 module Envoy
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 end

data/lib/envoy.rb

@@ -8,6 +8,10 @@ require "envoy/engine"
 require "envoy/errors"
 require "envoy/tool_definition"
 require "envoy/toolset"
+require "envoy/prompt"
+require "envoy/library"
+require "envoy/surface"
+require "envoy/page_surface"
 require "envoy/guard"
 require "envoy/compiled_tool"
 require "envoy/llm"
@@ -41,5 +45,60 @@ module Envoy
     def toolset(key)
       toolsets.fetch(key.to_s) { raise UnknownToolset, "no toolset #{key.inspect}" }
     end
+
+    def prompts
+      @prompts ||= {}
+    end
+
+    def define_prompt(key, &block)
+      prompt = Prompt.new(key)
+      prompt.instance_eval(&block)
+      prompts[prompt.key] = prompt
+    end
+
+    def prompt(key)
+      prompts.fetch(key.to_s) { raise UnknownPrompt, "no prompt #{key.inspect}" }
+    end
+
+    def libraries
+      @libraries ||= {}
+    end
+
+    # Registers both the Library (for introspection) and its compiled Toolset
+    # under the same key, so `use :principles` works like any other toolset.
+    def define_library(key, &block)
+      library = Library.new(key)
+      library.instance_eval(&block)
+      libraries[library.key] = library
+      toolsets[library.key] = library.to_toolset
+      library
+    end
+
+    def library(key)
+      libraries.fetch(key.to_s) { raise UnknownLibrary, "no library #{key.inspect}" }
+    end
+
+    def surfaces
+      @surfaces ||= {}
+    end
+
+    def define_surface(key, &block)
+      surface = Surface.new(key)
+      surface.instance_eval(&block)
+      surfaces[surface.key] = surface
+    end
+
+    def surface(key)
+      surfaces.fetch(key.to_s) { raise UnknownSurface, "no surface #{key.inspect}" }
+    end
+
+    # Resolve every surface's lazy references in one pass. Hosts call this at the
+    # end of the to_prepare block that loads their definitions, so a typo fails
+    # on boot rather than inside a job — where the failure is invisible and the
+    # user watches "working…" forever.
+    def validate!
+      surfaces.each_value(&:validate!)
+      true
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: envoy_ai
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Travis Petticrew
@@ -62,11 +62,12 @@ extra_rdoc_files: []
 files:
 - MIT-LICENSE
 - README.md
+- app/assets/stylesheets/envoy/chat.css
 - app/assets/stylesheets/envoy/console.css
 - app/controllers/envoy/application_controller.rb
 - app/controllers/envoy/conversations_controller.rb
 - app/controllers/envoy/messages_controller.rb
-- app/controllers/envoy/system_prompts_controller.rb
+- app/controllers/envoy/panels_controller.rb
 - app/javascript/envoy/controllers/autoscroll_controller.js
 - app/javascript/envoy/controllers/composer_controller.js
 - app/jobs/envoy/application_job.rb
@@ -74,30 +75,25 @@ files:
 - app/models/envoy/application_record.rb
 - app/models/envoy/conversation.rb
 - app/models/envoy/message.rb
-- app/models/envoy/system_prompt.rb
-- app/models/envoy/system_prompt_version.rb
 - app/models/envoy/tool_call.rb
 - app/views/envoy/conversations/_composer_input.html.erb
 - app/views/envoy/conversations/index.html.erb
 - app/views/envoy/conversations/new.html.erb
 - app/views/envoy/conversations/show.html.erb
+- app/views/envoy/messages/_error.html.erb
 - app/views/envoy/messages/_message.html.erb
 - app/views/envoy/messages/_streaming.html.erb
 - app/views/envoy/messages/_tool_call.html.erb
 - app/views/envoy/messages/create.turbo_stream.erb
-- app/views/envoy/system_prompts/_form.html.erb
-- app/views/envoy/system_prompts/edit.html.erb
-- app/views/envoy/system_prompts/index.html.erb
-- app/views/envoy/system_prompts/new.html.erb
-- app/views/envoy/system_prompts/show.html.erb
+- app/views/envoy/panels/_panel.html.erb
+- app/views/envoy/panels/_transcript.html.erb
 - app/views/layouts/envoy/application.html.erb
 - config/routes.rb
 - db/migrate/20260710000001_create_envoy_conversations.rb
 - db/migrate/20260710000002_create_envoy_messages.rb
 - db/migrate/20260710000003_create_envoy_tool_calls.rb
-- db/migrate/20260711000001_create_envoy_system_prompts.rb
-- db/migrate/20260711000002_create_envoy_system_prompt_versions.rb
-- db/migrate/20260711000003_add_system_prompt_version_to_envoy_conversations.rb
+- db/migrate/20260716000001_drop_envoy_system_prompts.rb
+- db/migrate/20260716000002_add_surface_to_envoy_conversations.rb
 - lib/envoy.rb
 - lib/envoy/badges.rb
 - lib/envoy/compiled_tool.rb
@@ -105,9 +101,13 @@ files:
 - lib/envoy/engine.rb
 - lib/envoy/errors.rb
 - lib/envoy/guard.rb
+- lib/envoy/library.rb
 - lib/envoy/llm.rb
 - lib/envoy/markdown.rb
+- lib/envoy/page_surface.rb
+- lib/envoy/prompt.rb
 - lib/envoy/runner.rb
+- lib/envoy/surface.rb
 - lib/envoy/testing/fake_llm.rb
 - lib/envoy/tool_definition.rb
 - lib/envoy/toolset.rb

data/app/controllers/envoy/system_prompts_controller.rb

@@ -1,52 +0,0 @@
-module Envoy
-  class SystemPromptsController < ApplicationController
-    def index
-      @system_prompts = SystemPrompt.order(:name)
-    end
-
-    def show
-      @system_prompt = SystemPrompt.find(params[:id])
-    end
-
-    def new
-      @system_prompt = SystemPrompt.new
-    end
-
-    def create
-      @system_prompt = SystemPrompt.new(prompt_params.except(:body))
-      body = prompt_params[:body].to_s
-      if body.blank?
-        @system_prompt.errors.add(:base, "Body can't be blank")
-        return render :new, status: :unprocessable_entity
-      end
-      SystemPrompt.transaction do
-        @system_prompt.save!
-        @system_prompt.add_version!(body)
-      end
-      redirect_to system_prompt_path(@system_prompt), notice: "Prompt created."
-    rescue ActiveRecord::RecordInvalid
-      render :new, status: :unprocessable_entity
-    end
-
-    def edit
-      @system_prompt = SystemPrompt.find(params[:id])
-    end
-
-    def update
-      @system_prompt = SystemPrompt.find(params[:id])
-      if @system_prompt.update(prompt_params.except(:body))
-        body = prompt_params[:body].to_s
-        @system_prompt.add_version!(body) if body.present? && body != @system_prompt.current_body
-        redirect_to system_prompt_path(@system_prompt), notice: "Prompt updated."
-      else
-        render :edit, status: :unprocessable_entity
-      end
-    end
-
-    private
-
-    def prompt_params
-      params.require(:system_prompt).permit(:name, :description, :body)
-    end
-  end
-end

data/app/models/envoy/system_prompt.rb

@@ -1,24 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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/views/envoy/system_prompts/_form.html.erb

@@ -1,14 +0,0 @@
-<%= 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

@@ -1,2 +0,0 @@
-<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

@@ -1,14 +0,0 @@
-<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

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