envoy_ai 0.0.1 → 0.0.2

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.2"
 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.2
 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" %>

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

@@ -1,15 +0,0 @@
-<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/db/migrate/20260711000001_create_envoy_system_prompts.rb

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

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

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