mistri 0.4.1 → 0.6.0

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,19 +5,23 @@ 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"
 require_relative "mistri/transport"
 require_relative "mistri/schema"
+require_relative "mistri/task_output"
 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"
@@ -34,10 +38,15 @@ require_relative "mistri/compaction"
 require_relative "mistri/stores/memory"
 require_relative "mistri/stores/jsonl"
 require_relative "mistri/session"
+require_relative "mistri/child"
+require_relative "mistri/locks"
+require_relative "mistri/console"
+require_relative "mistri/dispatchers"
 require_relative "mistri/compactor"
 require_relative "mistri/result"
 require_relative "mistri/agent"
 require_relative "mistri/sub_agent"
+require_relative "mistri/spawner"
 require_relative "mistri/mcp"
 require_relative "mistri/sinks/action_cable"
 require_relative "mistri/sinks/sse"
@@ -49,18 +58,25 @@ 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",
                   gemini: "GEMINI_API_KEY" }.freeze
 
+  # The configured lock adapter, nil until a host sets one. See Locks.
+  class << self
+    attr_accessor :locks
+  end
+
   module_function
 
   # Build a provider for a model, inferring which one from the model id and
   # 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}" }

data/mistri.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/mistri/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "mistri"
+  spec.version = Mistri::VERSION
+  spec.authors = ["Muhammad Ahmed Cheema"]
+  spec.summary = "The agent harness for Ruby applications."
+  spec.description = "Mistri (مستری) is the fixer: an agent harness that lives inside your " \
+                     "app. Durable sessions in your own store, streaming, tools, " \
+                     "fire-and-forget human approval, steering, compaction, structured " \
+                     "output, skills, and sub-agents, across Anthropic, OpenAI, and " \
+                     "Gemini, with zero runtime dependencies."
+  spec.homepage = "https://mistri.sh"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["source_code_uri"] = "https://github.com/mcheemaa/mistri"
+  spec.metadata["changelog_uri"] = "https://github.com/mcheemaa/mistri/blob/main/CHANGELOG.md"
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["documentation_uri"] =
+    "https://github.com/mcheemaa/mistri/blob/v#{spec.version}/docs/README.md"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/mcheemaa/mistri/issues"
+
+  # The .tt generator templates must ship, or rails g mistri:install breaks.
+  public_files = Dir["lib/**/*.{rb,tt}", "docs/**/*.md", "assets/**/*", "examples/*.rb"]
+                 .select { |path| File.file?(path) }
+  root_files = %w[CHANGELOG.md CONTRIBUTING.md LICENSE NOTICE README.md SECURITY.md
+                  UPGRADING.md mistri.gemspec]
+  spec.files = (public_files + root_files).sort
+  spec.require_paths = ["lib"]
+end