mistri 0.5.0 → 0.6.0

data/lib/mistri/usage.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Mistri
   # Token accounting for an assistant turn, and the dollar cost of those tokens.
   #
@@ -9,37 +11,77 @@ module Mistri
   # of `cache_write` held for an hour, which bills at twice the input rate.
   class Usage < Data.define(:input, :output, :cache_read, :cache_write,
                             :cache_write_1h, :reasoning, :cost)
+    # Dollar amounts plus whether every contributing token had known pricing.
+    # Known stays outside the released Data shape so pattern matching and
+    # positional construction remain compatible.
     Cost = Data.define(:input, :output, :cache_read, :cache_write, :total) do
-      def self.zero = new(input: 0.0, output: 0.0, cache_read: 0.0, cache_write: 0.0, total: 0.0)
+      def initialize(input:, output:, cache_read:, cache_write:, total:, known: true)
+        @known = known == true
+        super(input:, output:, cache_read:, cache_write:, total:)
+      end
+
+      def self.zero
+        new(input: 0.0, output: 0.0, cache_read: 0.0, cache_write: 0.0,
+            total: 0.0, known: true)
+      end
+
+      def self.unknown
+        new(input: 0.0, output: 0.0, cache_read: 0.0, cache_write: 0.0,
+            total: 0.0, known: false)
+      end
+
+      def known? = defined?(@known) ? @known : true
+
+      def with(**changes)
+        self.class.new(**to_h, **changes)
+      end
 
       def +(other)
         self.class.new(input: input + other.input, output: output + other.output,
                        cache_read: cache_read + other.cache_read,
                        cache_write: cache_write + other.cache_write,
-                       total: total + other.total)
+                       total: total + other.total, known: known? && other.known?)
       end
+
+      def ==(other) = super && known? == other.known?
+
+      alias_method :eql?, :==
+
+      def hash = [super, known?].hash
+
+      def to_h = super.merge(known: known?)
+
+      def _dump(_level) = JSON.generate(to_h)
+
+      def self._load(payload) = new(**JSON.parse(payload, symbolize_names: true))
     end
 
     def initialize(input: 0, output: 0, cache_read: 0, cache_write: 0,
-                   cache_write_1h: 0, reasoning: 0, cost: Cost.zero)
+                   cache_write_1h: 0, reasoning: 0, cost: Cost.unknown)
       super
     end
 
-    def self.zero = new
+    def self.zero = new(cost: Cost.zero)
 
     def self.from_h(hash)
       h = (hash || {}).transform_keys(&:to_s)
       c = (h["cost"] || {}).transform_keys(&:to_s)
-      new(input: h.fetch("input", 0).to_i, output: h.fetch("output", 0).to_i,
-          cache_read: h.fetch("cache_read", 0).to_i, cache_write: h.fetch("cache_write", 0).to_i,
-          cache_write_1h: h.fetch("cache_write_1h", 0).to_i,
-          reasoning: h.fetch("reasoning", 0).to_i,
-          cost: Cost.new(input: c.fetch("input", 0).to_f, output: c.fetch("output", 0).to_f,
-                         cache_read: c.fetch("cache_read", 0).to_f,
-                         cache_write: c.fetch("cache_write", 0).to_f,
-                         total: c.fetch("total", 0).to_f))
+      counts = { input: h.fetch("input", 0).to_i, output: h.fetch("output", 0).to_i,
+                 cache_read: h.fetch("cache_read", 0).to_i,
+                 cache_write: h.fetch("cache_write", 0).to_i,
+                 cache_write_1h: h.fetch("cache_write_1h", 0).to_i,
+                 reasoning: h.fetch("reasoning", 0).to_i }
+      amounts = { input: c.fetch("input", 0).to_f, output: c.fetch("output", 0).to_f,
+                  cache_read: c.fetch("cache_read", 0).to_f,
+                  cache_write: c.fetch("cache_write", 0).to_f,
+                  total: c.fetch("total", 0).to_f }
+      known = c.fetch("known", false) == true
+      known ||= !c.key?("known") && counts.values.all?(&:zero?) && amounts.values.all?(&:zero?)
+      new(**counts, cost: Cost.new(**amounts, known:))
     end
 
+    def prompt_tokens = input + cache_read + cache_write
+
     def total_tokens = input + output + cache_read + cache_write
 
     # A copy with cost computed from per-million-token rates. The 1h cache-write
@@ -54,7 +96,9 @@ module Mistri
         cache_read: rate(rates, :cache_read) * cache_read,
         cache_write: (rate(rates, :cache_write) * short) + (long_write_rate(rates) * long)
       }
-      with(cost: Cost.new(**computed, total: computed.values.sum))
+      with(cost: Cost.new(**computed,
+                          total: computed.values.sum,
+                          known: rates_cover?(rates, short, long)))
     end
 
     def +(other)
@@ -75,5 +119,13 @@ module Mistri
     def long_write_rate(rates)
       rates.key?(:cache_write_1h) ? rate(rates, :cache_write_1h) : rate(rates, :input) * 2
     end
+
+    def rates_cover?(rates, short, long)
+      (input.zero? || rates.key?(:input)) &&
+        (output.zero? || rates.key?(:output)) &&
+        (cache_read.zero? || rates.key?(:cache_read)) &&
+        (short.zero? || rates.key?(:cache_write)) &&
+        (long.zero? || rates.key?(:cache_write_1h) || rates.key?(:input))
+    end
   end
 end

data/lib/mistri/version.rb

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

data/lib/mistri/workspace/active_record.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
+require_relative "../workspace"
+
 module Mistri
   module Workspace
     # Documents in the host's own database, through a model class the host
     # supplies, optionally scoped (per session, per tenant). Not auto-required;
     # load it with require "mistri/workspace/active_record".
     #
-    # The model needs a path column and a content column, unique on path
-    # within the scope. A migration to copy:
+    # The model needs a non-null primary key plus non-null path, content, and
+    # scope columns, with a unique index whose columns are exactly the scope
+    # plus path. Atomic edits use that index plus a short row-locking
+    # transaction; no lock_version column is required. A migration to copy:
     #
     #   create_table :mistri_documents do |t|
     #     t.string :session_id, null: false
@@ -17,9 +21,24 @@ module Mistri
     #   end
     #   add_index :mistri_documents, [:session_id, :path], unique: true
     class ActiveRecord
+      MYSQL_ADAPTERS = %w[Mysql2 Trilogy].freeze
+      private_constant :MYSQL_ADAPTERS
+
       def initialize(model, scope: {})
+        raise ArgumentError, "scope must be a Hash" unless scope.is_a?(Hash)
+
+        names = scope.keys.map(&:to_s)
+        if names.uniq.length != names.length
+          raise ArgumentError, "scope keys must name distinct columns"
+        end
+
+        reserved = names & %w[path content]
+        unless reserved.empty?
+          raise ArgumentError, "scope cannot contain #{reserved.map(&:inspect).join(" or ")}"
+        end
+
         @model = model
-        @scope = scope
+        @scope = own_scope(scope)
       end
 
       def read(path)
@@ -33,6 +52,38 @@ module Mistri
         nil
       end
 
+      def atomic_writes?
+        return @atomic_writes if defined?(@atomic_writes)
+
+        @atomic_writes = atomic_storage?
+      end
+
+      def snapshot(path)
+        verify_atomic_context!
+        content = relation(path).pick(:content)
+        content.nil? ? nil : Snapshot.for(content.to_s)
+      end
+
+      def compare_and_write(path, content, expected_revision:)
+        verify_atomic_context!
+        key = path.to_s
+        return create_if_absent(key, content) if expected_revision.nil?
+
+        @model.transaction do
+          record = @model.lock.find_by(**@scope, path: key)
+          actual = record && Snapshot.for(record.content.to_s).revision
+          unless actual == expected_revision
+            raise WorkspaceConflictError.new(
+              key, expected_revision:, actual_revision: actual
+            )
+          end
+
+          record.content = content.to_s
+          record.save!
+          committed_snapshot(record, key)
+        end
+      end
+
       def delete(path)
         @model.where(**@scope, path: path.to_s).delete_all
         nil
@@ -42,6 +93,135 @@ module Mistri
         paths = @model.where(**@scope).pluck(:path).sort
         prefix ? paths.select { |p| p.start_with?(prefix.to_s) } : paths
       end
+
+      private
+
+      def verify_atomic_context!
+        unless atomic_writes?
+          adapter = @model.connection.adapter_name
+          raise ConfigurationError,
+                "atomic Active Record workspace writes require PostgreSQL or InnoDB, " \
+                "a matching non-null primary key, non-null scope/path/content columns, " \
+                "and an exact unique scope/path key; #{@model.table_name.inspect} on " \
+                "#{adapter} does not qualify"
+        end
+        return unless @model.connection.transaction_open?
+
+        raise ConfigurationError,
+              "atomic Active Record workspace operations cannot join an open transaction"
+      end
+
+      def relation(path) = @model.where(**@scope, path: path.to_s)
+
+      def create_if_absent(path, content)
+        @model.transaction do
+          record = @model.create!(**@scope, path:, content: content.to_s)
+          committed_snapshot(record, path)
+        end
+      rescue ::ActiveRecord::RecordNotUnique
+        raise unless relation(path).exists?
+
+        actual = snapshot(path)&.revision
+        raise WorkspaceConflictError.new(path, actual_revision: actual)
+      end
+
+      def atomic_storage?
+        adapter = @model.connection.adapter_name
+        supported = adapter == "PostgreSQL" ||
+                    (MYSQL_ADAPTERS.include?(adapter) && innodb_table?)
+        supported && atomic_schema?
+      end
+
+      def innodb_table?
+        connection = @model.connection
+        database, table = mysql_table_coordinates(connection)
+        sql = "SELECT ENGINE FROM information_schema.TABLES " \
+              "WHERE TABLE_SCHEMA = #{connection.quote(database)} " \
+              "AND TABLE_NAME = #{connection.quote(table)}"
+        connection.select_value(sql, "SCHEMA")&.casecmp?("InnoDB") == true
+      end
+
+      def mysql_table_coordinates(connection)
+        names = @model.table_name.to_s.split(".", 2)
+        return names if names.length == 2
+
+        [connection.current_database, names.first]
+      end
+
+      def atomic_schema?
+        connection = @model.connection
+        columns = connection.columns(@model.table_name).to_h { |column| [column.name, column] }
+        primary_columns = Array(@model.primary_key).compact.map(&:to_s)
+        catalog_primary = Array(connection.primary_keys(@model.table_name)).map(&:to_s)
+        return false unless primary_columns.sort == catalog_primary.sort
+        return false if primary_columns.empty? || !singular_scope?
+
+        required_columns = (@scope.keys.map(&:to_s) + %w[path content]).uniq
+        required_columns.concat(primary_columns).uniq!
+        return false unless non_null_columns?(columns, required_columns)
+
+        identity = (@scope.keys.map(&:to_s) + ["path"]).uniq.sort
+        return true if catalog_primary.sort == identity
+
+        exact_unique_identity?(connection, identity)
+      end
+
+      def exact_unique_identity?(connection, identity)
+        connection.indexes(@model.table_name).any? do |index|
+          valid = !index.respond_to?(:valid?) || index.valid?
+          columns = Array(index.columns).map(&:to_s).sort
+          index.unique && valid && !index.where && columns == identity
+        end
+      end
+
+      def non_null_columns?(columns, required)
+        required.all? do |name|
+          column = columns[name]
+          column && !column.null
+        end
+      end
+
+      def committed_snapshot(record, path)
+        identity = Array(@model.primary_key).compact.to_h do |column|
+          attributes = record.attributes
+          value = attributes.fetch(column.to_s) { attributes.fetch(column.to_sym) }
+          [column.to_sym, value]
+        end
+        if identity.empty?
+          raise ConfigurationError, "atomic Active Record workspace needs a primary key"
+        end
+
+        content = @model.where(**identity, **@scope, path:).pick(:content)
+        if content.nil?
+          raise SchemaError, "document #{path.inspect} changed identity during its write"
+        end
+
+        Snapshot.for(content.to_s)
+      end
+
+      def singular_scope?
+        @scope.values.all? do |value|
+          case value
+          when String, Symbol, Numeric, TrueClass, FalseClass, Time then true
+          else defined?(Date) && value.is_a?(Date)
+          end
+        end
+      end
+
+      def own_scope(value)
+        case value
+        when Hash
+          value.to_h { |key, item| [own_scope(key), own_scope(item)] }.freeze
+        when Array
+          value.map { |item| own_scope(item) }.freeze
+        when Range
+          Range.new(own_scope(value.begin), own_scope(value.end), value.exclude_end?).freeze
+        when String
+          String.new(value).freeze
+        else
+          value
+        end
+      end
     end
   end
 end

data/lib/mistri/workspace/directory.rb

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require_relative "../workspace"
 
 module Mistri
   module Workspace
-    # Documents as files under one root. Every path resolves inside the root
-    # or raises, so a model-supplied "../../etc/passwd" cannot escape.
+    # Documents as ordinary files under a host-controlled root. Model-supplied
+    # paths cannot escape lexically or traverse an existing symlink. The host
+    # must keep the root and tree stable for the instance's lifetime; this is
+    # not an OS sandbox against concurrent filesystem mutation.
     class Directory
       def initialize(root)
-        @root = File.expand_path(root)
-        FileUtils.mkdir_p(@root)
+        expanded = File.expand_path(root)
+        FileUtils.mkdir_p(expanded)
+        @root = File.realpath(expanded)
+        @root_prefix = @root.end_with?(File::SEPARATOR) ? @root : "#{@root}#{File::SEPARATOR}"
       end
 
       def read(path)
@@ -20,6 +25,7 @@ module Mistri
       def write(path, content)
         full = resolve(path)
         FileUtils.mkdir_p(File.dirname(full))
+        full = resolve(path)
         File.write(full, content.to_s)
         nil
       end
@@ -31,9 +37,13 @@ module Mistri
       end
 
       def list(prefix = nil)
-        base = @root.length + 1
-        paths = Dir.glob(File.join(@root, "**", "*")).select { |f| File.file?(f) }
-                                                     .map { |f| f[base..] }.sort
+        paths = Dir.glob("**/*", base: @root).filter_map do |path|
+          full = File.join(@root, path)
+          next if traverses_symlink?(full)
+          next unless File.file?(full)
+
+          path
+        end.sort
         prefix ? paths.select { |p| p.start_with?(prefix.to_s) } : paths
       end
 
@@ -41,12 +51,22 @@ module Mistri
 
       def resolve(path)
         full = File.expand_path(path.to_s, @root)
-        unless full == @root || full.start_with?("#{@root}#{File::SEPARATOR}")
+        unless full == @root || full.start_with?(@root_prefix)
           raise SchemaError, "path escapes the workspace: #{path}"
         end
+        raise SchemaError, "path traverses a symlink: #{path}" if traverses_symlink?(full)
 
         full
       end
+
+      def traverses_symlink?(full)
+        current = @root
+        relative = full.delete_prefix(@root).delete_prefix(File::SEPARATOR)
+        relative.split(File::SEPARATOR).any? do |part|
+          current = File.join(current, part)
+          File.symlink?(current)
+        end
+      end
     end
   end
 end

data/lib/mistri/workspace/memory.rb

@@ -1,14 +1,10 @@
 # frozen_string_literal: true
 
+require_relative "../workspace"
+
 module Mistri
-  # The document store agents work in. A workspace maps paths to text and can
-  # live anywhere: memory for tests and ephemeral runs, a directory when disk
-  # exists, the host's database when it does not. The file tools bind to this
-  # port, so fuzzy-editing a MySQL row works exactly like editing a file.
-  #
-  # A backend implements read(path) -> String or nil, write(path, content),
-  # delete(path), and list(prefix = nil) -> [paths].
   module Workspace
+    # A mutex-protected ephemeral document map with atomic conditional writes.
     class Memory
       def initialize
         @documents = {}
@@ -16,14 +12,39 @@ module Mistri
       end
 
       def read(path)
-        @mutex.synchronize { @documents[path.to_s] }
+        @mutex.synchronize { @documents[path.to_s]&.dup }
       end
 
       def write(path, content)
-        @mutex.synchronize { @documents[path.to_s] = content.to_s.dup.freeze }
+        @mutex.synchronize { @documents[path.to_s] = own(content) }
         nil
       end
 
+      def atomic_writes? = true
+
+      def snapshot(path)
+        @mutex.synchronize do
+          content = @documents[path.to_s]
+          content && Snapshot.for(content)
+        end
+      end
+
+      def compare_and_write(path, content, expected_revision:)
+        @mutex.synchronize do
+          key = path.to_s
+          current = @documents[key]
+          actual = current && Snapshot.for(current).revision
+          unless actual == expected_revision
+            raise WorkspaceConflictError.new(
+              key, expected_revision:, actual_revision: actual
+            )
+          end
+
+          @documents[key] = own(content)
+          Snapshot.for(@documents[key])
+        end
+      end
+
       def delete(path)
         @mutex.synchronize { @documents.delete(path.to_s) }
         nil
@@ -35,6 +56,10 @@ module Mistri
           prefix ? keys.select { |key| key.start_with?(prefix.to_s) } : keys
         end
       end
+
+      private
+
+      def own(content) = String.new(content.to_s).freeze
     end
   end
 end

data/lib/mistri/workspace/single.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../workspace"
+
 module Mistri
   module Workspace
     # One document living wherever the host says: a column on a record, a
@@ -9,15 +11,26 @@ module Mistri
     #   workspace = Mistri::Workspace::Single.new(
     #     path: "page.html",
     #     read: -> { page.reload.draft_html },
-    #     write: ->(html) { page.update!(draft_html: html) }
+    #     write: ->(html) { page.update!(draft_html: html) },
+    #     synchronize: lambda do |&operation|
+    #       raise "outer transaction" if page.class.connection.transaction_open?
+    #       page.with_lock(&operation)
+    #     end
     #   )
     #
     # The document tools then read and edit that column like any document.
+    # synchronize: is optional; without it, the legacy read/write port cannot
+    # protect an edit from another process writing between those two calls.
     class Single
-      def initialize(read:, write:, path: "document")
-        @path = path.to_s
+      def initialize(read:, write:, path: "document", synchronize: nil)
+        unless synchronize.nil? || synchronize.respond_to?(:call)
+          raise ArgumentError, "synchronize must be callable"
+        end
+
+        @path = String.new(path.to_s).freeze
         @read = read
         @write = write
+        @synchronize = synchronize
       end
 
       def read(path)
@@ -25,12 +38,44 @@ module Mistri
       end
 
       def write(path, content)
-        raise SchemaError, "this workspace holds only #{@path.inspect}" unless path.to_s == @path
+        verify_path!(path)
 
-        @write.call(content.to_s)
+        synchronize { @write.call(content.to_s) }
         nil
       end
 
+      def atomic_writes? = !@synchronize.nil?
+
+      def snapshot(path)
+        return nil unless path.to_s == @path
+
+        content = @read.call
+        content.nil? ? nil : Snapshot.for(content.to_s)
+      end
+
+      def compare_and_write(path, content, expected_revision:)
+        verify_path!(path)
+        unless atomic_writes?
+          raise ConfigurationError, "Single needs synchronize: for atomic writes"
+        end
+
+        synchronize do
+          current = @read.call
+          actual = current.nil? ? nil : Snapshot.for(current.to_s).revision
+          unless actual == expected_revision
+            raise WorkspaceConflictError.new(
+              @path, expected_revision:, actual_revision: actual
+            )
+          end
+
+          @write.call(content.to_s)
+          committed = @read.call
+          raise SchemaError, "#{@path.inspect} disappeared after write" if committed.nil?
+
+          Snapshot.for(committed.to_s)
+        end
+      end
+
       def delete(path)
         if path.to_s == @path
           raise SchemaError,
@@ -43,6 +88,18 @@ module Mistri
       def list(prefix = nil)
         prefix.nil? || @path.start_with?(prefix.to_s) ? [@path] : []
       end
+
+      private
+
+      def verify_path!(path)
+        return if path.to_s == @path
+
+        raise SchemaError, "this workspace holds only #{@path.inspect}"
+      end
+
+      def synchronize(&operation)
+        @synchronize ? @synchronize.call(&operation) : operation.call
+      end
     end
   end
 end

data/lib/mistri/workspace.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "errors"
+
+module Mistri
+  # The host-neutral document boundary. Every workspace supports ordinary
+  # read/write/delete/list; atomic_writes? opts into snapshot and conditional
+  # write semantics that remain correct across processes when its backend does.
+  module Workspace
+    MAX_REVISION_BYTES = 256
+    private_constant :MAX_REVISION_BYTES
+
+    # One immutable document representation and the opaque token that binds a
+    # later conditional write to these exact bytes.
+    Snapshot = Data.define(:content, :revision) do
+      def initialize(content:, revision:)
+        raise ArgumentError, "snapshot content must be a String" unless content.is_a?(String)
+        raise ArgumentError, "snapshot revision must be a String" unless revision.is_a?(String)
+
+        owned_content = String.new(content)
+        owned_revision = String.new(revision)
+        unless !owned_revision.empty? && owned_revision.bytesize <= MAX_REVISION_BYTES
+          raise ArgumentError,
+                "snapshot revision must be 1-#{MAX_REVISION_BYTES} bytes"
+        end
+
+        super(content: owned_content.freeze, revision: owned_revision.freeze)
+      end
+
+      def self.for(content)
+        raise ArgumentError, "snapshot content must be a String" unless content.is_a?(String)
+
+        owned = String.new(content)
+        new(content: owned, revision: Digest::SHA256.hexdigest(owned.b))
+      end
+    end
+  end
+end

data/lib/mistri.rb

@@ -5,10 +5,12 @@ require_relative "mistri/errors"
 require_relative "mistri/stop_reason"
 require_relative "mistri/usage"
 require_relative "mistri/models"
+require_relative "mistri/tool_arguments"
 require_relative "mistri/tool_call"
 require_relative "mistri/content"
 require_relative "mistri/message"
 require_relative "mistri/event"
+require_relative "mistri/event_delivery"
 require_relative "mistri/abort_signal"
 require_relative "mistri/sse"
 require_relative "mistri/partial_json"
@@ -19,6 +21,7 @@ require_relative "mistri/edit"
 require_relative "mistri/tool_context"
 require_relative "mistri/tool_result"
 require_relative "mistri/tool"
+require_relative "mistri/workspace"
 require_relative "mistri/workspace/memory"
 require_relative "mistri/workspace/directory"
 require_relative "mistri/workspace/single"
@@ -55,6 +58,8 @@ require_relative "mistri/providers/gemini"
 
 # Mistri (مستری): the fixer. An agent harness for Ruby applications.
 module Mistri
+  private_constant :ToolArguments
+
   PROVIDERS = { anthropic: Providers::Anthropic, openai: Providers::OpenAI,
                 gemini: Providers::Gemini }.freeze
   API_KEY_ENV = { anthropic: "ANTHROPIC_API_KEY", openai: "OPENAI_API_KEY",
@@ -71,7 +76,7 @@ module Mistri
   # reading its key from the environment unless one is passed.
   #
   #   Mistri.provider("claude-opus-4-8")
-  #   Mistri.provider("gpt-5.5", api_key: key, reasoning: { effort: "high" })
+  #   Mistri.provider("gpt-5.6", api_key: key, reasoning: { effort: "high" })
   def provider(model, api_key: nil, **)
     name = provider_name(model)
     klass = PROVIDERS.fetch(name) { raise ConfigurationError, "no provider for #{model.inspect}" }