envoy_ai 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65af52593c07af82aa70d2e0f32876bebf053d6cd1cce31cdaf914fe76aac996
-  data.tar.gz: a0c236d33db995bdbd8e1bcbb6ff7eab428ac6aba5d4294b7b49273efbda16c6
+  metadata.gz: 91cc30ece48d5717f72bedaa2a6bb2ca693e237411c89fcf394988a15d5f34ce
+  data.tar.gz: a581c3c845910a89433ca60189ea62657b66dac927f66ca829394978cd7074c4
 SHA512:
-  metadata.gz: 98ff01d5c0134a18f4f39809b5e881418ea8e38d4117e84351ec4dd13e34db1a0b589f8cde715f6c07c147534f3af5fa96022254eceef09c8aec86d36bcaee8b
-  data.tar.gz: abebd4786665308b9988f3bed11333f34b7603803a57e7cdd98eed26b205e86572626882629467a52fb204664e3d6f0a9760456d367df286185fdf14414743a2
+  metadata.gz: fc2294c5a6538b7daca827b967f69c87701ba103eb73cfe03910075efac5938f96a2fe4d593e77176ad6694258603199f7b4862feed2cca4b71d239927baeebd
+  data.tar.gz: f01ee674e09999df11d161ccc7c7f9cfea299e923cb656bfc06e69633bb6c958f78e2eb00454d2f984ef172f6e49f64408a2a07bb63848bf01ba474d256d40ae

data/README.md

@@ -135,14 +135,19 @@ result) — a user can only see and post to their own conversations.
 ## 5. Migrations
 
 Envoy ships its own migrations (`envoy_conversations`, `envoy_messages`,
-`envoy_tool_calls`, `envoy_system_prompts`, `envoy_system_prompt_versions`,
-plus the FK linking a conversation to the system-prompt version it used):
+`envoy_tool_calls`, plus `surface_key`/`context_key`/`prompt_key` columns on
+`envoy_conversations` for surface-bound and DSL-prompt conversations):
 
 ```bash
 bin/rails envoy:install:migrations
 bin/rails db:migrate
 ```
 
+If you installed Envoy before this version, `envoy:install:migrations` also
+copies over a migration that drops `envoy_system_prompts` and
+`envoy_system_prompt_versions` — see the Unreleased section of the CHANGELOG
+before running `db:migrate` on an app with real rows in those tables.
+
 ## 6. Assets
 
 The engine ships two Stimulus controllers under its own `app/javascript`
@@ -341,6 +346,180 @@ bundle exec bin/test test/envoy/guard_test.rb
 bundle exec bin/test test/envoy/guard_test.rb:12
 ```
 
+## 12. Embedding a chat
+
+The console (section 6 onward) is a full page. Most hosts instead want a small
+chat panel bolted onto an existing page — "ask about this record" next to a
+show view, say — without adopting the console's chrome or its mounted URL.
+That's what a **surface** is for: it binds a page to a toolset, a model and a
+prompt, and a mounted `POST` endpoint turns that binding into a Turbo Frame
+you can drop anywhere.
+
+### Define a surface
+
+```ruby
+# config/initializers/envoy.rb, alongside the toolset force-load block
+Envoy.define_surface :today do
+  toolset :assistant                # a registered Envoy.define_toolset key
+  model "claude-sonnet-4-5"          # optional; falls back to config.default_model
+  system_prompt :today_page          # a Prompt key (see below), or a literal String
+  read_only true                     # optional; hides `access :write` tools entirely
+
+  # Runs in the job for every turn — see the callout below.
+  context do |actor:, key:|
+    date = key.delete_prefix("day:")
+    "The user is looking at the training day for #{date}."
+  end
+end
+```
+
+`toolset` is required; `Envoy.validate!` (see below) fails fast if it names an
+unregistered toolset or an unregistered `system_prompt` key. `model`,
+`read_only` and `system_prompt` are all optional.
+
+### Define prompts and libraries
+
+`Envoy.define_prompt` registers reusable system-prompt text, composable with
+`use` (like a toolset) so shared framing lives in one place:
+
+```ruby
+Envoy.define_prompt :safety_framing do
+  body "Never invent data; say when you don't know."
+end
+
+Envoy.define_prompt :today_page do
+  use :safety_framing
+  body { File.read(Rails.root.join("app/envoy/prompts/today_page.md")) }
+end
+```
+
+A block body stays lazy, so editing the file on disk is picked up on the next
+`to_prepare` reload rather than requiring a boot.
+
+`Envoy.define_library` is for reference documents the model should fetch on
+demand rather than have preloaded into every turn's instructions — it
+compiles to an ordinary toolset (so it composes via `use` on a real
+toolset), exposing one `read_<key>` tool with a closed `enum` of document
+keys:
+
+```ruby
+Envoy.define_library :principles do
+  directory Rails.root.join("docs/principles")   # README.md -> description, *.md -> documents
+end
+
+Envoy.define_toolset :assistant do
+  description "General assistant tools."
+  use :principles
+end
+```
+
+### Wire a page to it
+
+Any host controller can call `envoy_surface` — it's mixed into
+`ActionController::Base` by the engine, no include needed:
+
+```ruby
+class TodayController < ApplicationController
+  envoy_surface :today, context_key: -> { "day:#{@date.to_fs(:iso8601)}" }
+end
+```
+
+`context_key` is instance_exec'd in the controller, so instance variables the
+action set (`@date` here) are in scope. The helper method `envoy_page_surface`
+(available in views) returns `{ surface:, context_key: }`, or `nil` if the
+controller never declared a surface — pages opt in, they don't get a bubble by
+default.
+
+> **A `context` block runs in the job.** There is no request, no `params` and
+> no session — only `actor` and `key`. Everything it needs must be derivable
+> from the `context_key`. It is also the authorization boundary: `surface` and
+> `context_key` both arrive from the browser, so raise `Envoy::Forbidden` if
+> this actor may not see this subject.
+
+### Render the panel
+
+`POST envoy.panel_path` (mounted by `resource :panel, only: :create`) finds
+or creates the conversation for `(actor, surface, context_key)` and renders it
+inside a `turbo_frame_tag "envoy_panel"`. Point a `button_to` at it with a
+matching frame already on the page — same "create-or-resume" semantics as
+opening a tab twice, so re-clicking never duplicates the conversation:
+
+```erb
+<% if (surface = envoy_page_surface) %>
+  <%= turbo_frame_tag "envoy_panel" %>
+  <%= button_to "Ask about this page", envoy.panel_path,
+        params: { surface: surface[:surface], context_key: surface[:context_key] },
+        data: { turbo_frame: "envoy_panel" } %>
+<% end %>
+```
+
+An unregistered `surface` param renders `404`; the endpoint is otherwise
+subject to the same `authenticate`/`actor_resolver` config as every other
+Envoy route, so a signed-out visitor never reaches it.
+
+### Style it
+
+The panel (and the console) render the same
+`app/views/envoy/panels/_transcript.html.erb` partial, styled entirely by
+`app/assets/stylesheets/envoy/chat.css` — no body rules, no fixed widths, the
+host owns the chrome around it. `console.css` pulls it in automatically
+(`@import url("chat.css")`, so loading the console stylesheet already gives
+you these rules too), or import it directly from the host's own stylesheet if
+you don't want the console's chrome at all:
+
+```css
+@import url("envoy/chat.css");
+```
+
+Use the `url(...)` form, not a bare string — Propshaft only fingerprints
+`url(...)` references in CSS, not `@import` strings, and its asset server
+404s on an undigested path.
+
+Every color it uses is a CSS custom property, and every declaration falls
+back to its own original console value when the var is unset, so it renders
+reasonably with zero host configuration and themes cleanly by setting only
+the vars below:
+
+| Var | Affects | Fallback (console light mode) |
+|---|---|---|
+| `--envoy-surface` | message bubble / input background | `#ffffff` |
+| `--envoy-surface-alt` | assistant bubble background *and* tool-call panel background | `#eff6ff` / `#f9fafb` (each rule keeps its own original shade until you set this) |
+| `--envoy-ink` | body text | `#111827` |
+| `--envoy-subtle` | role labels, hints, placeholder text | `#6b7280` |
+| `--envoy-line` | borders | `#e5e7eb` |
+| `--envoy-accent` | primary button background | `#111827` |
+| `--envoy-accent-ink` | primary button text | `#ffffff` |
+| `--envoy-warn` | the failed-turn error bubble | `#b91c1c` |
+| `--envoy-radius` | corner rounding (message/tool/input/button each keep their own default until set) | `0.5rem` / `0.375rem` |
+
+Setting `--envoy-surface-alt` or `--envoy-radius` themes every rule that uses
+it identically; the console itself never sets them, so it keeps its original,
+slightly more varied look.
+
+### Assets and boot-time validation
+
+Pin the same two Stimulus controllers as the console (section 6) — the
+composer for Enter-to-submit, the autoscroll controller (now scrolls its own
+`.envoy-chat__log` container rather than the window, so it sticks the panel
+without hijacking the host page's scroll position):
+
+```ruby
+# config/importmap.rb
+pin "envoy/controllers/composer_controller", to: "envoy/controllers/composer_controller.js"
+pin "envoy/controllers/autoscroll_controller", to: "envoy/controllers/autoscroll_controller.js"
+```
+
+Finally, call `Envoy.validate!` at the end of the `to_prepare` block that
+force-loads your definitions, so a typo'd toolset or prompt key fails on boot
+— not silently, inside a job, where the user just watches "working…" forever:
+
+```ruby
+Rails.application.config.to_prepare do
+  Dir[Rails.root.join("app/envoy/**/*.rb")].each { |f| require_dependency f }
+  Envoy.validate!
+end
+```
+
 ## The debug console
 
 Envoy ships a minimal chat UI mounted at whatever path the host chooses

data/app/assets/stylesheets/envoy/chat.css

@@ -0,0 +1,236 @@
+/* Embeddable chat rules. No body, no page-level layout, no fixed widths —
+   the host owns the chrome. Every colour is a var with a fallback, so the
+   stylesheet stands alone in the console and themes cleanly in a host.
+
+   Public vars (all optional — every rule falls back to the console's own
+   light-mode palette when unset): --envoy-surface, --envoy-surface-alt,
+   --envoy-ink, --envoy-subtle, --envoy-line, --envoy-accent,
+   --envoy-accent-ink, --envoy-warn, --envoy-radius. */
+
+/* Fills a flex-column container (an embedded, fixed-height panel) so the log
+   below can scroll internally. Inert when the parent isn't a flex container —
+   e.g. the full-page console, which keeps its natural height and page-scrolls —
+   because flex item properties only apply inside a flex parent. The embedding
+   host is responsible for giving this element a bounded height (a flex column
+   with a definite height); the transcript then fills it and scrolls its log. */
+.envoy-chat {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  flex: 1 1 auto;
+}
+
+.envoy-chat__log {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  scrollbar-width: thin;
+  scrollbar-color: var(--envoy-subtle, #6b7280) transparent;
+}
+.envoy-chat__log::-webkit-scrollbar { width: 8px; }
+.envoy-chat__log::-webkit-scrollbar-track { background: transparent; }
+.envoy-chat__log::-webkit-scrollbar-thumb {
+  background: var(--envoy-subtle, #6b7280);
+  border-radius: 9999px;
+}
+.envoy-chat__log::-webkit-scrollbar-thumb:hover {
+  background: var(--envoy-ink, #111827);
+}
+
+/* Separate the transcript from the composer: in the flex column the log sits
+   flush against the input form, so the last message and the textarea run
+   together without a divider. */
+.envoy-chat > form {
+  margin-top: 0.75rem;
+  padding-top: 0.75rem;
+  border-top: 1px solid var(--envoy-line, #e5e7eb);
+}
+
+/* ---------------------------------------------------------------------- */
+/* Messages                                                               */
+/* ---------------------------------------------------------------------- */
+
+.envoy-msg {
+  border: 1px solid var(--envoy-line, #e5e7eb);
+  border-radius: var(--envoy-radius, 0.5rem);
+  padding: 1rem;
+  background: var(--envoy-surface, #ffffff);
+}
+.envoy-msg--assistant { background: var(--envoy-surface-alt, #eff6ff); }
+
+.envoy-msg__role {
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  color: var(--envoy-subtle, #6b7280);
+  margin-bottom: 0.25rem;
+}
+
+/* Subtle "working…" shimmer while a reply is being generated. */
+.envoy-working { animation: envoy-working 1.4s ease-in-out infinite; }
+@keyframes envoy-working {
+  0%, 100% { opacity: 0.4; }
+  50%      { opacity: 0.95; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .envoy-working { animation: none; opacity: 0.7; }
+}
+
+/* ---------------------------------------------------------------------- */
+/* Rendered markdown body                                                 */
+/* ---------------------------------------------------------------------- */
+
+.envoy-md { font-size: 0.9rem; line-height: 1.6; }
+.envoy-md > * + * { margin-top: 0.7rem; }
+.envoy-md h1 { font-size: 1.3em; font-weight: 700; }
+.envoy-md h2 { font-size: 1.15em; font-weight: 700; }
+.envoy-md h3, .envoy-md h4 { font-size: 1em; font-weight: 700; }
+.envoy-md ul { padding-left: 1.25rem; list-style: disc; }
+.envoy-md ol { padding-left: 1.25rem; list-style: decimal; }
+.envoy-md li + li { margin-top: 0.2rem; }
+.envoy-md a { text-decoration: underline; }
+.envoy-md blockquote { border-left: 3px solid rgba(128, 128, 128, 0.4); padding-left: 0.75rem; }
+.envoy-md hr { border: 0; border-top: 1px solid rgba(128, 128, 128, 0.3); }
+/* Fenced code (comrak carries its own dark background + inline styles). */
+.envoy-md pre { padding: 0.75rem 1rem; border-radius: 0.5rem; }
+/* Inline code gets a subtle theme-agnostic chip. */
+.envoy-md :not(pre) > code {
+  font-size: 0.9em;
+  overflow-wrap: anywhere;
+  background: rgba(128, 128, 128, 0.15);
+  padding: 0.1em 0.3em;
+  border-radius: 0.25rem;
+}
+
+/* Code blocks scroll within the message instead of spilling past it, with a
+   thin, theme-agnostic overlay scrollbar (mid-gray at 50% reads on both the
+   light tool-call panels and the dark highlighted blocks). Scoped to the
+   transcript log (.envoy-chat__log, see panels/_transcript.html.erb) rather
+   than an id, since message-list ids are conversation-scoped
+   (dom_id(conversation, :messages)) and no element has a literal
+   #envoy_messages id. */
+.envoy-chat__log pre {
+  overflow-x: auto;
+  max-width: 100%;
+  scrollbar-width: thin;
+  scrollbar-color: rgba(128, 128, 128, 0.5) transparent;
+}
+.envoy-chat__log pre::-webkit-scrollbar { height: 8px; }
+.envoy-chat__log pre::-webkit-scrollbar-track { background: transparent; }
+.envoy-chat__log pre::-webkit-scrollbar-thumb {
+  background: rgba(128, 128, 128, 0.5);
+  border-radius: 9999px;
+}
+.envoy-chat__log pre::-webkit-scrollbar-thumb:hover { background: rgba(128, 128, 128, 0.8); }
+
+/* ---------------------------------------------------------------------- */
+/* Tool calls                                                             */
+/* ---------------------------------------------------------------------- */
+
+.envoy-tool {
+  margin-top: 0.5rem;
+  font-size: 0.875rem;
+  border: 1px solid var(--envoy-line, #e5e7eb);
+  border-radius: var(--envoy-radius, 0.375rem);
+  padding: 0.5rem;
+  background: var(--envoy-surface-alt, #f9fafb);
+}
+
+.envoy-tool__summary {
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.envoy-tool pre {
+  font-size: 0.75rem;
+  margin-top: 0.5rem;
+  overflow-x: auto;
+  max-width: 100%;
+}
+
+.envoy-mono {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+
+/* Tool-call outcome badge (rendered by Envoy::Badges.outcome). Colors match
+   the original Tailwind red-100/amber-100/green-100 pairs; intentionally
+   scheme-independent (not vars), as the original badge had no dark variant. */
+.envoy-badge {
+  display: inline-block;
+  font-size: 0.75rem;
+  padding: 0.125rem 0.5rem;
+  border-radius: var(--envoy-radius, 0.375rem);
+  font-weight: 500;
+}
+.envoy-badge--ok     { background: #dcfce7; color: #166534; }
+.envoy-badge--failed { background: #fef3c7; color: #92400e; }
+.envoy-badge--denied { background: #fee2e2; color: #991b1b; }
+
+/* ---------------------------------------------------------------------- */
+/* Composer                                                               */
+/* ---------------------------------------------------------------------- */
+
+.envoy-composer {
+  display: flex;
+  gap: 0.5rem;
+  align-items: flex-end;
+}
+
+.envoy-input {
+  flex: 1;
+  border: 1px solid var(--envoy-line, #e5e7eb);
+  border-radius: var(--envoy-radius, 0.375rem);
+  padding: 0.5rem;
+  background: var(--envoy-surface, #ffffff);
+  color: var(--envoy-ink, #111827);
+}
+.envoy-input::placeholder { color: var(--envoy-subtle, #6b7280); opacity: 1; }
+
+.envoy-hint {
+  font-size: 0.75rem;
+  color: var(--envoy-subtle, #6b7280);
+  margin-top: 0.25rem;
+}
+
+/* ---------------------------------------------------------------------- */
+/* Buttons                                                                */
+/* ---------------------------------------------------------------------- */
+
+.envoy-btn {
+  padding: 0.375rem 0.75rem;
+  border-radius: var(--envoy-radius, 0.375rem);
+  background: var(--envoy-accent, #111827);
+  color: var(--envoy-accent-ink, #ffffff);
+  border: 0;
+  cursor: pointer;
+  text-decoration: none;
+  display: inline-block;
+  flex-shrink: 0;
+  font: inherit;
+}
+.envoy-btn--secondary {
+  background: transparent;
+  color: inherit;
+  border: 1px solid var(--envoy-line, #e5e7eb);
+}
+
+/* ---------------------------------------------------------------------- */
+/* Layout / state helpers                                                 */
+/* ---------------------------------------------------------------------- */
+
+.envoy-stack > * + * { margin-top: 1rem; }
+.envoy-stack--sm > * + * { margin-top: 0.75rem; }
+
+.envoy-muted {
+  color: var(--envoy-subtle, #6b7280);
+  font-size: 0.875rem;
+}
+
+/* A .envoy-msg modifier (see app/views/envoy/messages/_error.html.erb): turns
+   the assistant bubble's border and text red when a turn failed. */
+.envoy-error {
+  border-color: var(--envoy-warn, #b91c1c);
+  color: var(--envoy-warn, #b91c1c);
+}