mistri 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05f65dbeaf12ad0dc59334e300a2ecd2febc01607d528c0d8e7a95003c49e608
-  data.tar.gz: f1c261e05ee6e433f3b08f6c129841b6b25a44ee935671d3314681de792d0da5
+  metadata.gz: de242bfa63b5f170166c93613fc2a2807971d45b792a6200eb60805c4f41c977
+  data.tar.gz: 362d523bba1848e2b552ece5906b1554c4a54820379c9f8e7a3e93430144a9c1
 SHA512:
-  metadata.gz: 852c0bc7b87c7aa8b09b6862b88babbdbe3ddd6bd3e9736d8429818a3daaa98279fbe4f7703fd45e371ab78d7e76b0660ee19c47f183c760bcdba41d58bb6929
-  data.tar.gz: 2e97b19dfee548042488c16d4d37ddcdf5adf3959de7cd90d076e29c667021f2c07aec603eb8d6d0316ce944a027b55da9ca13f2adf3bc1647dac38b16316c0c
+  metadata.gz: 2ac330d28d201397f03912c893a538e824c5889a999f7afff3dde4cca8fe8e3a1263f4b886623f6c65fa6b732eae02962e72d4d9c6e945215f2aa724af1d82cb
+  data.tar.gz: fa27dd203af02953b311a479992e82f87e526c8b825b6be057ec0c4bffc0a76172b19af11e57ed7c522a15d0f8e063724b74dd5c5173f11118e96736457c4453

data/CHANGELOG.md

@@ -5,6 +5,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-05
+
+- Mistri::Definition: agents as frontmatter markdown files. Config in
+  YAML, prompt in the body, {placeholders} filled at build time and
+  unfilled ones raise. Tool names and extra keys stay the host's
+  vocabulary.
+- Agent context: Mistri.agent(context: anything) rides the run and reaches
+  every tool handler and hook as context.app, untouched.
+- Content::Image.from_data_uri accepts base64 data: URIs directly.
+
+- OpenAI reasoning summaries keep their paragraph structure: a reasoning
+  item's summary parts join with a blank line, and the boundary streams as
+  a thinking delta, so live views match the finished text.
+
 ## [0.3.0] - 2026-07-05
 
 - Sessions heal at replay: a run killed mid-tool (deploy, crash) leaves

data/README.md

@@ -12,7 +12,7 @@
 <p align="center">
   <a href="https://rubygems.org/gems/mistri"><img alt="Gem Version" src="https://img.shields.io/gem/v/mistri"></a>
   <a href="https://github.com/mcheemaa/mistri/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/mcheemaa/mistri/actions/workflows/ci.yml/badge.svg"></a>
-  <a href="https://codecov.io/gh/mcheemaa/mistri"><img alt="Coverage" src="https://codecov.io/gh/mcheemaa/mistri/graph/badge.svg"></a>
+  <a href="https://codecov.io/gh/mcheemaa/mistri"><img alt="Coverage" src="https://img.shields.io/codecov/c/github/mcheemaa/mistri"></a>
   <a href="mistri.gemspec"><img alt="Ruby >= 3.2" src="https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D"></a>
   <a href="Gemfile"><img alt="Runtime dependencies: zero" src="https://img.shields.io/badge/runtime_deps-0-brightgreen"></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
@@ -102,6 +102,20 @@ Mistri::Tool.define("edit_page", "Applies a page edit.") do |args|
 end
 ```
 
+Handlers and hooks can take the run's context as a second argument, and
+`context.app` carries whatever object you pass as `Mistri.agent(context:)`
+— the acting user, a tenant, a request — so tools stay authorization-aware
+without closure gymnastics:
+
+```ruby
+agent = Mistri.agent("claude-opus-4-8", tools: tools,
+                     context: { traveler: current_traveler })
+
+Mistri::Tool.define("book_hotel", "Books the chosen hotel.") do |args, context|
+  Bookings.create!(args, traveler: context.app[:traveler])
+end
+```
+
 ## Human approval
 
 Mark a tool `needs_approval: true` (or a predicate on its arguments) and the
@@ -110,12 +124,12 @@ The decision is a one-line session write from any process, any time later;
 `resume` settles it and carries on.
 
 ```ruby
-send_gift = Mistri::Tool.define("send_gift", "Sends a real gift.",
-                                needs_approval: ->(args) { args["amount"].to_i > 100 }) do |args|
-  Gifts.send!(args)
+book_hotel = Mistri::Tool.define("book_hotel", "Books the chosen hotel.",
+                                 needs_approval: ->(args) { args["total_usd"].to_i > 500 }) do |args|
+  Bookings.create!(args)
 end
 
-result = agent.run("Send Ana a $200 gift")
+result = agent.run("Book the corner suite for the Lisbon trip")
 result.awaiting_approval?   # => true; nothing executed
 
 # Days later, in a controller:
@@ -215,6 +229,20 @@ A skill is a `SKILL.md` (or flat `.md`) with `name:`/`description:`
 frontmatter, or built from database rows with
 `Mistri::Skill.new(name:, description:, body:)`.
 
+## Definitions
+
+An agent as a markdown file: YAML frontmatter for config, the body as the
+prompt, `{placeholders}` filled at build time (unfilled ones raise). Tool
+names and any extra keys stay your vocabulary; the gem only reads the
+file.
+
+```ruby
+definition = Mistri::Definition.load("app/agents/trip_planner.md")
+agent = Mistri.agent(definition.model,
+                     system: definition.render(first_name: traveler.first_name),
+                     tools: registry.build(definition.tools, traveler))
+```
+
 ## Sub-agents
 
 Delegate to a child agent with a clean context: exploration fills the
@@ -345,6 +373,7 @@ policy = Mistri::RetryPolicy.new(attempts: 3)
 
 ```ruby
 photo = Mistri::Content::Image.from_bytes(File.binread("chart.png"), mime_type: "image/png")
+photo = Mistri::Content::Image.from_data_uri(params[:image])   # canvases and uploads
 agent.run("What trend does this chart show?", images: [photo])
 
 Mistri.agent("gpt-5.5", provider_options: { reasoning: { effort: "high" } })

data/lib/mistri/agent.rb

@@ -30,7 +30,8 @@ module Mistri
     # return a replacement result, or nil to keep the original.
     def initialize(provider:, session: nil, system: nil, tools: [], budget: nil,
                    max_concurrency: 4, transform_context: nil, compaction: Compaction.new,
-                   retries: RetryPolicy.new, skills: [], before_tool: nil, after_tool: nil)
+                   retries: RetryPolicy.new, skills: [], before_tool: nil, after_tool: nil,
+                   context: nil)
       @provider = provider
       @session = session || Session.new(store: Stores::Memory.new)
       skills = skills.is_a?(String) ? Skills.load(skills) : Array(skills)
@@ -46,6 +47,7 @@ module Mistri
       @retries = retries || nil
       @before_tool = before_tool
       @after_tool = after_tool
+      @context = context
     end
 
     attr_reader :session
@@ -302,7 +304,8 @@ module Mistri
 
       results = ToolExecutor.call(calls, @tools_by_name, signal: signal,
                                                          max_concurrency: @max_concurrency,
-                                                         session: @session, emit: emit)
+                                                         session: @session, emit: emit,
+                                                         app: @context)
       context = hook_context(signal, emit)
       results.each do |call, result, seconds|
         result = rewrite(call, result, context) if @after_tool
@@ -337,7 +340,7 @@ module Mistri
     end
 
     def hook_context(signal, emit)
-      ToolContext.new(session: @session, signal: signal, emit: emit)
+      ToolContext.new(session: @session, signal: signal, emit: emit, app: @context)
     end
 
     # The tool message carries both channels; the :tool_result event exposes

data/lib/mistri/content.rb

@@ -50,6 +50,15 @@ module Mistri
       # second copy of what can be a multi-megabyte payload.
       def self.from_bytes(bytes, mime_type:) = new(data: [bytes.b].pack("m0").freeze, mime_type:)
 
+      # Browsers, canvases, and upload pipelines hand images around as
+      # data: URIs; accept them directly.
+      def self.from_data_uri(uri)
+        match = /\Adata:(?<mime>[^;,]+);base64,(?<data>.+)\z/m.match(uri.to_s)
+        raise ArgumentError, "not a base64 data: URI" unless match
+
+        new(data: match[:data].delete("\n").freeze, mime_type: match[:mime])
+      end
+
       def initialize(data:, mime_type:)
         super(data: Content.freeze_string(data), mime_type: Content.freeze_string(mime_type))
       end

data/lib/mistri/definition.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Mistri
+  # An agent definition: a markdown file whose YAML frontmatter carries the
+  # config and whose body is the prompt. Prompts stay editable prose in
+  # files a reviewer can diff; code stays out of them.
+  #
+  #   ---
+  #   role: Trip Planner
+  #   model: claude-opus-4-8
+  #   tools:
+  #     - search_flights
+  #     - book_hotel
+  #   ---
+  #   You plan trips end to end. Address the traveler as {first_name}.
+  #
+  #   definition = Mistri::Definition.load("app/agents/trip_planner.md")
+  #   agent = Mistri.agent(definition.model,
+  #                        system: definition.render(first_name: traveler.first_name),
+  #                        tools: registry.build(definition.tools, traveler))
+  #
+  # The gem reads the file; what tool names mean, and what any extra
+  # frontmatter keys mean, stays the host's vocabulary via #config.
+  class Definition
+    FRONTMATTER = /\A---\s*\n(?<yaml>.*?)\n---\s*\n(?<body>.*)\z/m
+
+    attr_reader :name, :body, :config
+
+    def self.load(path)
+      match = FRONTMATTER.match(File.read(path))
+      raise ConfigurationError, "#{path} has no frontmatter" unless match
+
+      config = YAML.safe_load(match[:yaml]) || {}
+      raise ConfigurationError, "#{path} frontmatter is not a mapping" unless config.is_a?(Hash)
+
+      new(name: File.basename(path.to_s, ".md"), config: config, body: match[:body].strip)
+    end
+
+    def initialize(name:, config:, body:)
+      @name = name.to_s
+      @config = config.freeze
+      @body = body
+      freeze
+    end
+
+    def model = config["model"]
+
+    def role = config["role"]
+
+    # Tool declarations as a name => options map. A bare list means no
+    # options; a map form carries per-tool options in the host's
+    # vocabulary (gates, caching, whatever the host honors).
+    def tools
+      raw = config["tools"]
+      entries = case raw
+                when Hash then raw.transform_values { |options| options || {} }
+                when Array then raw.to_h { |tool| [tool, {}] }
+                else {}
+                end
+      entries.transform_keys(&:to_s)
+    end
+
+    def tool_names = tools.keys
+
+    # The body with {placeholders} filled in. An unfilled placeholder
+    # raises: a prompt silently addressing "{first_name}" is worse than an
+    # error. A value of nil renders as empty, which lets optional context
+    # collapse cleanly.
+    def render(vars = {})
+      vars = vars.transform_keys(&:to_s)
+      body.gsub(/\{(\w+)\}/) do
+        vars.fetch(Regexp.last_match(1)) do |key|
+          raise ConfigurationError, "no value for {#{key}} in the #{name} definition"
+        end
+      end
+    end
+  end
+end

data/lib/mistri/providers/openai/assembler.rb

@@ -25,7 +25,8 @@ module Mistri
           case record["type"]
           when "response.output_item.added" then start_item(record["item"], &)
           when "response.output_text.delta" then text_delta(record["delta"], &)
-          when "response.reasoning_summary_text.delta" then thinking_delta(record["delta"], &)
+          when "response.reasoning_summary_text.delta"
+            thinking_delta(record["delta"], record["summary_index"], &)
           when "response.function_call_arguments.delta" then arguments_delta(record["delta"], &)
           when "response.output_item.done" then finish_item(record["item"], &)
           when "response.completed", "response.incomplete", "response.failed"
@@ -83,6 +84,7 @@ module Mistri
           return unless kind
 
           @current = Builder.new(kind, @blocks.size, +"", +"")
+          @summary_part = nil
           emit_event(:"#{kind}_start", content_index: @current.index, &)
         end
 
@@ -93,9 +95,17 @@ module Mistri
           emit_event(:text_delta, content_index: @current.index, delta: delta, &)
         end
 
-        def thinking_delta(delta, &)
+        # A reasoning item carries one or more summary parts, each its own
+        # paragraph; the boundary streams as a delta so live views keep the
+        # break the finished text will have.
+        def thinking_delta(delta, part, &)
           return unless @current
 
+          if @summary_part && part && part != @summary_part
+            @current.text << "\n\n"
+            emit_event(:thinking_delta, content_index: @current.index, delta: "\n\n", &)
+          end
+          @summary_part = part if part
           @current.text << delta.to_s
           emit_event(:thinking_delta, content_index: @current.index, delta: delta, &)
         end
@@ -131,7 +141,7 @@ module Mistri
             text = Array(item["content"]).filter_map { |part| part["text"] }.join
             Content::Text.new(text: text, signature: item["id"])
           when :thinking
-            summary = Array(item["summary"]).filter_map { |part| part["text"] }.join
+            summary = Array(item["summary"]).filter_map { |part| part["text"] }.join("\n\n")
             Content::Thinking.new(thinking: summary, signature: JSON.generate(item))
           when :toolcall
             ToolCall.new(id: item["call_id"], name: item["name"],

data/lib/mistri/tool_context.rb

@@ -2,13 +2,24 @@
 
 module Mistri
   # What a tool handler may know about the run it executes inside: the
-  # caller's session, the abort signal, and the event stream. Handlers take
-  # it as an optional second argument — a proc ignores it invisibly, a
-  # lambda opts in by accepting two parameters. Sub-agents are built on it;
-  # any tool that spawns work, links records to the session, or streams
-  # progress can use it the same way.
-  ToolContext = Data.define(:session, :signal, :emit) do
-    def initialize(session: nil, signal: nil, emit: nil)
+  # caller's session, the abort signal, the event stream, and the host's
+  # own context object. Handlers take it as an optional second argument — a
+  # proc ignores it invisibly, a lambda opts in by accepting two
+  # parameters. Sub-agents are built on it; any tool that spawns work,
+  # links records to the session, or streams progress can use it the same
+  # way.
+  #
+  # app carries whatever the host passes as Agent.new(context:) — the
+  # acting user, a tenant, a request — untouched. The gem provides the
+  # slot, never the vocabulary:
+  #
+  #   agent = Mistri.agent("claude-opus-4-8", tools: tools,
+  #                        context: { traveler: current_traveler })
+  #   Mistri::Tool.define("book_hotel", "Books the chosen hotel.") do |args, context|
+  #     Bookings.create(args, traveler: context.app[:traveler])
+  #   end
+  ToolContext = Data.define(:session, :signal, :emit, :app) do
+    def initialize(session: nil, signal: nil, emit: nil, app: nil)
       super
     end
   end

data/lib/mistri/tool_executor.rb

@@ -16,10 +16,12 @@ module Mistri
 
     module_function
 
-    def call(calls, tools_by_name, signal: nil, max_concurrency: 4, session: nil, emit: nil)
+    def call(calls, tools_by_name, signal: nil, max_concurrency: 4, session: nil, emit: nil,
+             app: nil)
       return [] if calls.empty?
 
-      context = ToolContext.new(session: session, signal: signal, emit: thread_safe(emit))
+      context = ToolContext.new(session: session, signal: signal, emit: thread_safe(emit),
+                                app: app)
       results = Array.new(calls.length)
       queue = Queue.new
       calls.each_with_index { |call, index| queue << [call, index] }

data/lib/mistri/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mistri
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/mistri.rb

@@ -23,6 +23,7 @@ require_relative "mistri/workspace/directory"
 require_relative "mistri/workspace/single"
 require_relative "mistri/memory"
 require_relative "mistri/tools"
+require_relative "mistri/definition"
 require_relative "mistri/skill"
 require_relative "mistri/skills"
 require_relative "mistri/tool_executor"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mistri
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Muhammad Ahmed Cheema
@@ -34,6 +34,7 @@ files:
 - lib/mistri/compaction.rb
 - lib/mistri/compactor.rb
 - lib/mistri/content.rb
+- lib/mistri/definition.rb
 - lib/mistri/edit.rb
 - lib/mistri/errors.rb
 - lib/mistri/event.rb