mistri 0.1.0 → 0.2.1

data/lib/mistri/mcp.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # Bridge Model Context Protocol servers into Mistri tools: list a server's
+  # tools, hand them to an agent, and everything the harness already does
+  # composes — approval gates on third-party write tools, retries, sub-agent
+  # pools, the ui channel.
+  #
+  #   client = Mistri::MCP::Client.new(url: "https://mcp.linear.app/mcp",
+  #                                    token: -> { connection.fresh_token })
+  #   agent = Mistri.agent("claude-opus-4-8",
+  #                        tools: Mistri::MCP.tools(client, prefix: "linear"))
+  #
+  # The bridge is duck-typed: any client responding to tools (an array of
+  # {"name", "description", "inputSchema"} hashes) and call_tool(name, args)
+  # bridges the same way, so the official mcp gem's client plugs in too.
+  module MCP
+    # A protocol-level failure: a JSON-RPC error, a missing response, an
+    # unsupported negotiation.
+    class Error < Mistri::Error
+      attr_reader :code
+
+      def initialize(message = nil, code: nil)
+        @code = code
+        super(message)
+      end
+    end
+
+    # The server expired this client's session (a 404 with a session
+    # attached); the spec says start a fresh one, and Client does.
+    class SessionExpired < Error; end
+
+    module_function
+
+    # The server's tools as Mistri tools. allow/deny filter by remote name,
+    # prefix namespaces local names ("linear__create_issue") against
+    # collisions, and gates marks tools needing human approval
+    # (gates: { "create_issue" => true }, or needs_approval: for all).
+    def tools(client, allow: nil, deny: [], prefix: nil, needs_approval: false, gates: {})
+      listed = client.tools
+      listed = listed.select { |tool| allow.include?(tool["name"]) } if allow
+      listed = listed.reject { |tool| deny.include?(tool["name"]) }
+      listed.map do |tool|
+        bridge(client, tool, prefix: prefix, gate: gates.fetch(tool["name"], needs_approval))
+      end
+    end
+
+    def bridge(client, spec, prefix: nil, gate: false)
+      remote = spec.fetch("name")
+      local = prefix ? "#{prefix}__#{remote}" : remote
+      Tool.define(local, spec["description"].to_s,
+                  input_schema: spec["inputSchema"] || Tool::EMPTY_SCHEMA,
+                  needs_approval: gate) do |args|
+        answer(client.call_tool(remote, args || {}))
+      end
+    end
+
+    # An MCP result becomes model-readable content: text joins, images ride
+    # as image blocks, and isError answers in band so the model can react.
+    def answer(result)
+      blocks = Array(result["content"]).map { |block| convert(block) }
+      if result["isError"]
+        text = blocks.grep(String).join("\n")
+        return "MCP tool error: #{text.empty? ? "unknown error" : text}"
+      end
+      if blocks.empty? && result["structuredContent"]
+        return JSON.generate(result["structuredContent"])
+      end
+      return blocks.join("\n") if blocks.all?(String)
+
+      blocks
+    end
+
+    def convert(block)
+      case block["type"]
+      when "text" then block["text"].to_s
+      when "image"
+        Content::Image.from_bytes(block["data"].to_s.unpack1("m"),
+                                  mime_type: block["mimeType"] || "image/png")
+      when "resource" then resource_text(block["resource"] || {})
+      when "resource_link" then "[resource: #{block["uri"]}]"
+      else "[unsupported #{block["type"]} content]"
+      end
+    end
+
+    def resource_text(resource)
+      resource["text"] || "[resource: #{resource["uri"]}]"
+    end
+  end
+end
+
+require_relative "mcp/wires"
+require_relative "mcp/client"
+require_relative "mcp/oauth"

data/lib/mistri/reminder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mistri
+  # A periodic reminder for long agentic runs: models drift from their
+  # instructions as turns accumulate, and a short reminder at the tail of
+  # the context, where attention is strongest, pulls them back. It rides
+  # transform_context, so it appears fresh on the wire each time it is due
+  # and never persists to the session.
+  #
+  #   agent = Mistri.agent("claude-opus-4-8", tools: tools,
+  #                        transform_context: Mistri::Reminder.every(
+  #                          3, "Stay on gifting. Verify with tools before claiming.",
+  #                        ))
+  #
+  # Due is counted in completed assistant turns: the first reminder lands
+  # once `after` turns have finished (default: one full interval), then
+  # every `interval` turns.
+  class Reminder
+    def self.every(interval, text, after: nil)
+      new(interval: interval, text: text, after: after)
+    end
+
+    def initialize(interval:, text:, after: nil)
+      @interval = [interval.to_i, 1].max
+      @after = (after || @interval).to_i
+      @body = "<system-reminder>\n#{text}\n</system-reminder>"
+    end
+
+    def call(messages)
+      turns = messages.count(&:assistant?)
+      return messages unless turns >= @after && ((turns - @after) % @interval).zero?
+
+      messages + [Message.user(@body)]
+    end
+  end
+end

data/lib/mistri/result.rb

@@ -9,9 +9,11 @@ module Mistri
   #
   # Reads delegate to the final message, so result.text works whether the run
   # completed or suspended.
-  # output is a task's validated value, nil on plain runs.
-  Result = Data.define(:message, :status, :pending, :output) do
-    def initialize(message:, status:, pending: [], output: nil)
+  # output is a task's validated value, nil on plain runs. usage is the
+  # run's own accounting: every persisted turn plus compaction calls, summed
+  # (a resumed run counts from the resume; task sums across its fix passes).
+  Result = Data.define(:message, :status, :pending, :output, :usage) do
+    def initialize(message:, status:, pending: [], output: nil, usage: Usage.zero)
       super
     end
 

data/lib/mistri/tool.rb

@@ -13,7 +13,7 @@ module Mistri
     # bare empty hash.
     EMPTY_SCHEMA = { type: "object", properties: {} }.freeze
 
-    attr_reader :name, :description, :input_schema
+    attr_reader :name, :description, :input_schema, :timeout
 
     # Define a tool. Give the argument shape as a raw JSON Schema hash via
     # input_schema:, or build it in Ruby with a schema: block.
@@ -28,7 +28,7 @@ module Mistri
     end
 
     def initialize(name:, description:, input_schema: EMPTY_SCHEMA, eager_input_streaming: false,
-                   needs_approval: false, &handler)
+                   needs_approval: false, timeout: nil, &handler)
       raise ArgumentError, "tool #{name.inspect} needs a handler block" unless handler
 
       @name = name.to_s
@@ -36,6 +36,7 @@ module Mistri
       @input_schema = input_schema
       @eager_input_streaming = eager_input_streaming
       @needs_approval = needs_approval
+      @timeout = timeout
       @handler = handler
     end
 

data/lib/mistri/tool_executor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module Mistri
   # Runs a turn's tool calls and returns their results in the order the model
   # emitted them, regardless of completion order. Independent calls run
@@ -23,7 +25,10 @@ module Mistri
       calls.each_with_index { |call, index| queue << [call, index] }
       workers = max_concurrency.clamp(1, calls.length)
       Array.new(workers) { worker(queue, results, tools_by_name, context) }.each(&:join)
-      calls.zip(results).map { |call, result| [call, result || INTERRUPTED] }
+      calls.zip(results).map do |call, entry|
+        value, seconds = entry || [INTERRUPTED, nil]
+        [call, value, seconds]
+      end
     end
 
     def worker(queue, results, tools_by_name, context)
@@ -34,8 +39,14 @@ module Mistri
           rescue ThreadError
             break
           end
-          interrupted = context.signal&.aborted?
-          results[index] = interrupted ? INTERRUPTED : run_one(call, tools_by_name, context)
+          if context.signal&.aborted?
+            results[index] = [INTERRUPTED, nil]
+            next
+          end
+
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          value = run_one(call, tools_by_name, context)
+          results[index] = [value, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started]
         end
       end
     end
@@ -44,11 +55,21 @@ module Mistri
       tool = tools_by_name[call.name]
       return "Error: unknown tool #{call.name.inspect}" unless tool
 
-      with_rails_executor { tool.call(call.arguments, context) }
+      with_rails_executor { invoke(tool, call, context) }
     rescue StandardError => e
       "Error running tool #{call.name.inspect}: #{e.class}: #{e.message}"
     end
 
+    # A tool with a timeout answers in band when it stalls, so one hung
+    # handler cannot stall the whole run.
+    def invoke(tool, call, context)
+      return tool.call(call.arguments, context) unless tool.timeout
+
+      Timeout.timeout(tool.timeout) { tool.call(call.arguments, context) }
+    rescue Timeout::Error
+      "Error running tool #{call.name.inspect}: timed out after #{tool.timeout}s"
+    end
+
     # Concurrent tools share the caller's sink; sinks are not required to be
     # thread-safe, so forwarded events serialize here.
     def thread_safe(emit)

data/lib/mistri/transport.rb

@@ -45,12 +45,53 @@ module Mistri
       @mutex.synchronize { stream_locked(path, body, headers, signal, &block) }
     end
 
+    # POST for Streamable-HTTP endpoints (the MCP shape) that answer either
+    # a JSON body or an SSE stream: yields each JSON record either way and
+    # returns the response headers, downcased. Retries only a dead idle
+    # socket that failed before any response started, so a side-effecting
+    # call can never run twice.
+    def post_either(path, body:, headers: {}, &block)
+      @mutex.synchronize do
+        retried = false
+        begin
+          started = false
+          response_headers = nil
+          connection.request(build_request(path, body, headers, streaming: true)) do |response|
+            started = true
+            raise_for_status(response)
+            response_headers = response.to_hash.transform_values(&:first)
+            read_either(response, &block)
+          end
+          response_headers
+        rescue IOError, SocketError, SystemCallError, Timeout::Error => e
+          teardown
+          if started || retried || e.is_a?(Timeout::Error)
+            raise ProviderError, "connection failed: #{e.message}"
+          end
+
+          retried = true
+          retry
+        end
+      end
+    end
+
     def close
       @mutex.synchronize { teardown }
     end
 
     private
 
+    def read_either(response, &block)
+      if response["content-type"].to_s.include?("text/event-stream")
+        sse = SSE.new
+        response.read_body { |chunk| sse.feed(chunk, &block) }
+        sse.finish(&block)
+      else
+        raw = response.read_body
+        block.call(JSON.parse(raw)) unless raw.to_s.strip.empty?
+      end
+    end
+
     def stream_locked(path, body, headers, signal, &block)
       retried = false
       begin

data/lib/mistri/version.rb

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

data/lib/mistri.rb

@@ -28,6 +28,7 @@ require_relative "mistri/skills"
 require_relative "mistri/tool_executor"
 require_relative "mistri/budget"
 require_relative "mistri/retry_policy"
+require_relative "mistri/reminder"
 require_relative "mistri/compaction"
 require_relative "mistri/stores/memory"
 require_relative "mistri/stores/jsonl"
@@ -36,6 +37,7 @@ require_relative "mistri/compactor"
 require_relative "mistri/result"
 require_relative "mistri/agent"
 require_relative "mistri/sub_agent"
+require_relative "mistri/mcp"
 require_relative "mistri/sinks/action_cable"
 require_relative "mistri/sinks/sse"
 require_relative "mistri/sinks/coalesced"

metadata

@@ -1,20 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: mistri
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Muhammad Ahmed Cheema
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: 'Mistri (مستری) is the fixer: an agent harness that lives inside your
   app. Durable sessions in your own database, streaming, tools, fire-and-forget human
   approval, steering, compaction, structured output, skills, and sub-agents, across
   Anthropic, OpenAI, and Gemini, with zero runtime dependencies.'
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -26,6 +24,9 @@ files:
 - lib/generators/mistri/install/install_generator.rb
 - lib/generators/mistri/install/templates/migration.rb.tt
 - lib/generators/mistri/install/templates/model.rb.tt
+- lib/generators/mistri/mcp/mcp_generator.rb
+- lib/generators/mistri/mcp/templates/migration.rb.tt
+- lib/generators/mistri/mcp/templates/model.rb.tt
 - lib/mistri.rb
 - lib/mistri/abort_signal.rb
 - lib/mistri/agent.rb
@@ -36,6 +37,10 @@ files:
 - lib/mistri/edit.rb
 - lib/mistri/errors.rb
 - lib/mistri/event.rb
+- lib/mistri/mcp.rb
+- lib/mistri/mcp/client.rb
+- lib/mistri/mcp/oauth.rb
+- lib/mistri/mcp/wires.rb
 - lib/mistri/memory.rb
 - lib/mistri/message.rb
 - lib/mistri/models.rb
@@ -50,6 +55,7 @@ files:
 - lib/mistri/providers/openai.rb
 - lib/mistri/providers/openai/assembler.rb
 - lib/mistri/providers/openai/serializer.rb
+- lib/mistri/reminder.rb
 - lib/mistri/result.rb
 - lib/mistri/retry_policy.rb
 - lib/mistri/schema.rb
@@ -85,14 +91,15 @@ files:
 - lib/mistri/workspace/directory.rb
 - lib/mistri/workspace/memory.rb
 - lib/mistri/workspace/single.rb
-homepage: https://github.com/mcheemaa/mistri
+homepage: https://mistri.sh
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/mcheemaa/mistri
   changelog_uri: https://github.com/mcheemaa/mistri/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
+  documentation_uri: https://mistri.sh/docs/getting-started/
+  bug_tracker_uri: https://github.com/mcheemaa/mistri/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -107,8 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: The agent harness for Ruby applications.
 test_files: []