praxo-core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 58af042d8ca9a28e2090a34faf13dbee0de142463fcb4ad98b16b697baac8554
+  data.tar.gz: 87919c6781c1dac6fd8f731289b02cf563e25d4a4fada8ad52321137236e97c6
+SHA512:
+  metadata.gz: a26816e4f1f02666c156f3607b4139b1bf3b28a1069e1be4b6853f1854fcbb63dc22217de302a7553713ee9c13c88e9a43a55cc3b689e3743bbc176f09d2c239
+  data.tar.gz: 7348cb7bde0fa6f0c47526b15a5b0c5a1f0b003ff06344205d12d770dfbbee8c2da6a421ee14c2b5f4e84173728e2a5c0857d7ff7d9ec3d2300709e9d42268b4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AxisVela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,66 @@
+# PRAXO-CORE Ruby Core
+
+PRAXO-CORE is an embeddable, MIT-licensed agent framework. This gem is its
+native Ruby Core: an agent loop with tool registration and dispatch, policy
+hooks, typed events, memory, checkpoints, context budgets, middleware, JSON
+Schema validation, and plugin manifest parsing.
+
+The normative contract is [`spec/`](../../spec/README.md); Go remains the
+reference implementation.
+
+- `SPEC_VERSION`: `0.2.0`
+- Core version: `0.1.0`
+- Tier: core
+- License: MIT
+- Dependencies: Ruby standard library only
+
+## Scope
+
+The Core implements all eleven vector groups: toolcall, JSON Schema, plugin,
+memory, event, stream, checkpoint, policy, context, middleware, and the agent
+loop. It includes a public API snapshot and a dependency-free test runner.
+
+## Build and test
+
+```bash
+ruby language/ruby/conformance/run.rb
+ruby language/ruby/api-snapshot.rb --check
+ruby language/ruby/tests/run.rb
+```
+
+## Quickstart
+
+```ruby
+$LOAD_PATH.unshift('language/ruby/lib')
+require 'praxo'
+
+model = Praxo::Agent::StaticModel.new('hello')
+options = Praxo::Agent::AgentOptions.new(model)
+result = Praxo::Agent.run_agent(
+  options,
+  Praxo::Models.session(id: 'demo'),
+  'hello'
+)
+puts result.output
+```
+
+Tools register on the options object:
+
+```ruby
+registry = Praxo::Agent::ToolRegistry.new
+registry.register(Praxo::Agent::FuncTool.new('echo', 'Echo arguments',
+                                             ->(arguments) { arguments }))
+options.tools = registry
+options.max_steps = 8
+```
+
+## Layout
+
+- `lib/praxo/` package source.
+- `conformance/run.rb` vector runner.
+- `api-snapshot.rb` and `api/` public API snapshot.
+- `tests/run.rb` test suite.
+
+## Release
+
+Tag shape: `ruby/v0.1.0`. The tag targets `SPEC_VERSION` `0.2.0`.

data/api/0.1.0.txt

@@ -0,0 +1,110 @@
+# PRAXO-CORE Ruby API 0.1.0
+# SPEC_VERSION 0.2.0
+
+class AgentOptions
+class CallLimit
+class CheckpointAllowlist
+class ContextBudget
+class Error
+class FilterSink
+class FuncTool
+class MemoryStore
+class MultiSink
+class PathChecker
+class PiiRedactor
+class Runner
+class StaticModel
+class StructuredOutput
+class ToolRegistry
+class ToolSelection
+def action
+def allowed?
+def allows?
+def apply
+def array
+def as_int
+def as_object
+def as_string
+def authorize
+def before_model
+def before_tool
+def bool
+def check
+def check_enum
+def check_keys
+def compact
+def content_block
+def decision
+def emit
+def equals
+def error
+def error_code
+def estimate_tokens
+def event
+def extract_json
+def fallback_model
+def filter
+def generate
+def get
+def has?
+def initialize
+def int
+def invoke
+def invoke_tool
+def marshal
+def memory_record
+def message
+def message_assistant
+def message_text
+def message_tool
+def message_wire
+def parse
+def parse_input_json
+def parse_json_call
+def parse_manifest
+def parse_plain
+def parse_tag
+def parse_toolcall
+def parse_xml
+def plus
+def put
+def redact
+def redact_value
+def register
+def reject
+def request
+def resolve_path
+def response
+def run
+def run_agent
+def run_result
+def search
+def session
+def specs
+def string
+def stringify
+def strip_markup
+def structured_apply
+def text_present
+def tool_call
+def tool_spec
+def truncate_to_tokens
+def unmarshal
+def usage
+def validate
+def visit
+def visit_array
+def visit_boolean
+def visit_number
+def visit_object
+def visit_string
+def within?
+module Agent
+module Json
+module JsonSchema
+module Middleware
+module Models
+module Plugin
+module Praxo
+module Runtime
+module Toolcall

data/lib/praxo/agent.rb

@@ -0,0 +1,162 @@
+require_relative 'errors'
+require_relative 'json'
+require_relative 'models'
+require_relative 'runtime'
+
+module Praxo
+  module Agent
+    class FuncTool
+      attr_reader :name, :description
+
+      def initialize(name, description, function)
+        @name = name
+        @description = description
+        @function = function
+      end
+
+      def invoke(arguments)
+        @function.call(arguments)
+      end
+    end
+
+    class ToolRegistry
+      def initialize
+        @tools = {}
+      end
+
+      def register(tool)
+        @tools[tool.name] = tool
+        tool
+      end
+
+      def get(name)
+        Praxo.error('TOOL_NOT_FOUND', "tool not found: #{name}") unless @tools.key?(name)
+        @tools[name]
+      end
+
+      def specs
+        @tools.values.map do |tool|
+          Models.tool_spec(name: tool.name, description: tool.description)
+        end.sort_by(&:name)
+      end
+    end
+
+    class StaticModel
+      def initialize(content)
+        @content = content.to_s
+      end
+
+      def generate(_request)
+        Models.response(message: Models.message_assistant(@content))
+      end
+    end
+
+    class AgentOptions
+      attr_accessor :model, :tools, :events, :policy, :system_prompt, :context,
+                    :max_steps, :max_tokens, :tool_choice
+
+      def initialize(model)
+        @model = model
+        @tools = nil
+        @events = nil
+        @policy = nil
+        @system_prompt = ''
+        @context = nil
+        @max_steps = 8
+        @max_tokens = 0
+        @tool_choice = nil
+      end
+    end
+
+    class Runner
+      def initialize(options)
+        @options = options
+      end
+
+      def run(session, prompt)
+        options = @options
+        max_steps = options.max_steps.to_i.positive? ? options.max_steps : 8
+        run_id = "run-#{(Time.now.to_f * 1000).to_i}"
+        messages = session.messages.dup
+        unless options.system_prompt.to_s.empty?
+          messages.unshift(Models.message_text(Models::SYSTEM, options.system_prompt))
+        end
+        messages << Models.message_text(Models::USER, prompt.to_s)
+        usage = Models.usage
+        emit(options, 'run.started', session.id, run_id)
+        begin
+          (1..max_steps).each do |step|
+            authorize(options, Models.action(kind: 'model.generate', session_id: session.id))
+            if options.context
+              compacted, ok = options.context.compact(messages)
+              Praxo.error('AGENT_CONTEXT_BUDGET', 'context budget') unless ok
+              messages = compacted
+            end
+            request = Models.request(
+              messages: messages,
+              tools: options.tools ? options.tools.specs : [],
+              tool_choice: options.tool_choice
+            )
+            response = options.model.generate(request)
+            usage = usage.plus(response.usage || Models.usage)
+            total = usage.input_tokens.to_i + usage.output_tokens.to_i
+            if options.max_tokens.to_i.positive? && total > options.max_tokens
+              Praxo.error('AGENT_MAX_TOKENS', 'token budget')
+            end
+            message = response.message
+            messages << message
+            calls = message.tool_calls || []
+            if calls.empty?
+              emit(options, 'run.completed', session.id, run_id)
+              return Models.run_result(
+                run_id: run_id, output: message.content.to_s, steps: step,
+                usage: usage
+              )
+            end
+            calls.each do |call|
+              messages << invoke_tool(options, call, run_id, session.id)
+            end
+          end
+          Praxo.error('AGENT_MAX_STEPS', 'maximum steps')
+        rescue StandardError => e
+          emit(options, 'run.failed', session.id, run_id, { 'error' => e.message })
+          raise
+        end
+      end
+
+      private
+
+      def invoke_tool(options, call, run_id, session_id)
+        authorize(options, Models.action(
+          kind: 'tool.invoke', session_id: session_id,
+          tool_name: call.name, arguments: call.arguments
+        ))
+        Praxo.error('TOOL_NOT_FOUND', 'tool is not registered') unless options.tools
+        tool = options.tools.get(call.name)
+        emit(options, 'tool.call', session_id, run_id,
+             { 'name' => call.name, 'arguments' => call.arguments || {} })
+        value = tool.invoke(call.arguments || {})
+        Models.message_tool(Json.stringify(value), call.id.to_s)
+      end
+
+      def authorize(options, action)
+        return unless options.policy
+        decision = options.policy.call(action)
+        Praxo.error('POLICY_ERROR', 'policy denied the action') unless decision&.allowed
+      end
+
+      def emit(options, type, session_id, run_id, data = nil)
+        return unless options.events
+        options.events.emit(Models.event(
+          type: type, session_id: session_id, run_id: run_id, data: data
+        ))
+      end
+    end
+
+    module_function
+
+    def run_agent(options, session, prompt)
+      Runner.new(options).run(session, prompt)
+    end
+  end
+end

data/lib/praxo/errors.rb

@@ -0,0 +1,18 @@
+module Praxo
+  class Error < StandardError
+    attr_reader :code
+
+    def initialize(code, message)
+      @code = code
+      super(message)
+    end
+  end
+
+  def self.error(code, message)
+    raise Error.new(code, message)
+  end
+
+  def self.error_code(error)
+    error.is_a?(Error) ? error.code : ''
+  end
+end

data/lib/praxo/json.rb

@@ -0,0 +1,47 @@
+require 'json'
+
+module Praxo
+  module Json
+    module_function
+
+    def parse(text)
+      JSON.parse(text)
+    end
+
+    def stringify(value)
+      JSON.generate(value)
+    end
+
+    def get(node, key)
+      node.is_a?(Hash) ? node[key] : nil
+    end
+
+    def has?(node, key)
+      node.is_a?(Hash) && node.key?(key)
+    end
+
+    def string(node, key)
+      value = get(node, key)
+      value.is_a?(String) ? value : nil
+    end
+
+    def bool(node, key, fallback = false)
+      value = get(node, key)
+      value == true || value == false ? value : fallback
+    end
+
+    def int(node, key, fallback = 0)
+      value = get(node, key)
+      value.is_a?(Numeric) ? value.to_i : fallback
+    end
+
+    def array(node, key)
+      value = get(node, key)
+      value.is_a?(Array) ? value : []
+    end
+
+    def equals(left, right)
+      left == right
+    end
+  end
+end

data/lib/praxo/jsonschema.rb

@@ -0,0 +1,122 @@
+require_relative 'json'
+
+module Praxo
+  module JsonSchema
+    ValidationError = Struct.new(:path, :message, keyword_init: true)
+
+    module_function
+
+    def validate(schema, data)
+      errors = []
+      visit(schema, data, '$', errors)
+      errors
+    end
+
+    def visit(schema, data, path, errors)
+      return unless schema.is_a?(Hash)
+      type = schema['type'].is_a?(String) ? schema['type'] : ''
+      if data.nil?
+        errors << ValidationError.new(path: path, message: "expected #{type}, got null") unless type.empty?
+        return
+      end
+      case type
+      when 'object' then visit_object(schema, data, path, errors)
+      when 'array' then visit_array(schema, data, path, errors)
+      when 'string' then visit_string(schema, data, path, errors)
+      when 'number', 'integer' then visit_number(schema, type, data, path, errors)
+      when 'boolean' then visit_boolean(schema, data, path, errors)
+      end
+    end
+
+    def visit_object(schema, data, path, errors)
+      unless data.is_a?(Hash)
+        errors << ValidationError.new(path: path, message: 'expected object')
+        return
+      end
+      Array(schema['required']).each do |name|
+        next unless name.is_a?(String)
+        unless data.key?(name)
+          errors << ValidationError.new(path: "#{path}.#{name}", message: 'required field missing')
+        end
+      end
+      properties = schema['properties']
+      if properties.is_a?(Hash)
+        properties.each do |name, child|
+          visit(child, data[name], "#{path}.#{name}", errors) if data.key?(name)
+        end
+      end
+    end
+
+    def visit_array(schema, data, path, errors)
+      unless data.is_a?(Array)
+        errors << ValidationError.new(path: path, message: 'expected array')
+        return
+      end
+      items = schema['items']
+      return unless items.is_a?(Hash)
+      data.each_with_index { |value, index| visit(items, value, "#{path}[#{index}]", errors) }
+    end
+
+    def visit_string(schema, data, path, errors)
+      unless data.is_a?(String)
+        errors << ValidationError.new(path: path, message: 'expected string')
+        return
+      end
+      length = data.length
+      min = schema['minLength'].is_a?(Numeric) ? schema['minLength'].to_i : 0
+      max = schema['maxLength'].is_a?(Numeric) ? schema['maxLength'].to_i : 0
+      if min.positive? && length < min
+        errors << ValidationError.new(path: path, message: "min length #{min}, got #{length}")
+      end
+      if max.positive? && length > max
+        errors << ValidationError.new(path: path, message: "max length #{max}, got #{length}")
+      end
+      if schema['pattern'].is_a?(String)
+        begin
+          regex = Regexp.new(schema['pattern'])
+          unless regex.match?(data)
+            errors << ValidationError.new(path: path,
+              message: "pattern '#{schema['pattern']}' not matched")
+          end
+        rescue RegexpError
+          errors << ValidationError.new(path: path,
+            message: "invalid pattern '#{schema['pattern']}'")
+        end
+      end
+      check_enum(schema, data, path, errors)
+    end
+
+    def visit_number(schema, type, data, path, errors)
+      unless data.is_a?(Numeric)
+        errors << ValidationError.new(path: path, message: 'expected number')
+        return
+      end
+      if type == 'integer' && data.to_i != data
+        errors << ValidationError.new(path: path, message: "expected integer, got #{data}")
+        return
+      end
+      check_enum(schema, data, path, errors)
+      if schema['minimum'].is_a?(Numeric) && schema['minimum'] != 0 && data < schema['minimum']
+        errors << ValidationError.new(path: path, message: 'value below minimum')
+      end
+      if schema['maximum'].is_a?(Numeric) && schema['maximum'] != 0 && data > schema['maximum']
+        errors << ValidationError.new(path: path, message: 'value above maximum')
+      end
+    end
+
+    def visit_boolean(schema, data, path, errors)
+      unless data == true || data == false
+        errors << ValidationError.new(path: path, message: 'expected boolean')
+        return
+      end
+      check_enum(schema, data, path, errors)
+    end
+
+    def check_enum(schema, data, path, errors)
+      values = schema['enum']
+      return unless values.is_a?(Array) && !values.empty?
+      return if values.any? { |value| Json.equals(value, data) }
+      errors << ValidationError.new(path: path, message: 'value not in enum')
+    end
+  end
+end

data/lib/praxo/middleware.rb

@@ -0,0 +1,133 @@
+require_relative 'errors'
+require_relative 'json'
+require_relative 'jsonschema'
+require_relative 'models'
+
+module Praxo
+  module Middleware
+    class PiiRedactor
+      RULES = [
+        [/[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}/, '[REDACTED:email]'],
+        [/\b\d{3}-\d{2}-\d{4}\b/, '[REDACTED:ssn]'],
+        [/\b(?:\d{4}[ -]?){3}\d{4}\b/, '[REDACTED:credit_card]']
+      ].freeze
+
+      def redact(text)
+        output = text.to_s.dup
+        RULES.each { |pattern, replacement| output.gsub!(pattern, replacement) }
+        output
+      end
+
+      def redact_value(value)
+        case value
+        when String then redact(value)
+        when Array then value.map { |item| redact_value(item) }
+        when Hash then value.transform_values { |item| redact_value(item) }
+        else value
+        end
+      end
+    end
+
+    class StructuredOutput
+      def initialize(schema:, max_repairs: 0, repairer: nil)
+        @schema = schema
+        @max_repairs = max_repairs
+        @repairer = repairer
+      end
+
+      def apply(text)
+        output = text.to_s
+        (0..@max_repairs).each do |attempt|
+          begin
+            data = Middleware.extract_json(output)
+            return [output, nil] if JsonSchema.validate(@schema, data).empty?
+          rescue StandardError
+            nil
+          end
+          break if attempt == @max_repairs && @repairer.nil?
+          break unless @repairer
+          repaired = @repairer.call(output)
+          break if repaired.nil? || repaired.strip.empty?
+          output = repaired
+        end
+        [nil, 'AGENT_STRUCTURED_OUTPUT']
+      end
+    end
+
+    class CallLimit
+      def initialize(model_limit:, tool_limit:)
+        @model_limit = model_limit
+        @tool_limit = tool_limit
+        @models = 0
+        @tools = 0
+      end
+
+      def before_model
+        @models += 1
+        if @model_limit.positive? && @models > @model_limit
+          Praxo.error('AGENT_MODEL_CALL_LIMIT', 'model call limit')
+        end
+      end
+
+      def before_tool
+        @tools += 1
+        if @tool_limit.positive? && @tools > @tool_limit
+          Praxo.error('AGENT_TOOL_CALL_LIMIT', 'tool call limit')
+        end
+      end
+    end
+
+    class ToolSelection
+      def initialize(selected)
+        @selected = selected.to_h { |name| [name, true] }
+      end
+
+      def filter(tools)
+        tools.select { |tool| @selected[tool.name] }
+      end
+
+      def reject(name)
+        Praxo.error('AGENT_TOOL_NOT_SELECTED', 'tool not selected') unless @selected[name]
+      end
+    end
+
+    module_function
+
+    def extract_json(text)
+      value = text.to_s.strip
+      if value.start_with?('```')
+        newline = value.index("\n")
+        value = value[(newline + 1)..] if newline
+        value = value.gsub(/\A`+/, '').gsub(/`+\z/, '').strip
+      end
+      start = [value.index('{'), value.index('[')].compact.min
+      raise Praxo::Error.new('AGENT_STRUCTURED_OUTPUT', 'output does not contain JSON') if start.nil?
+      Json.parse(value[start..])
+    end
+
+    def redact(text)
+      PiiRedactor.new.redact(text)
+    end
+
+    def redact_value(value)
+      PiiRedactor.new.redact_value(value)
+    end
+
+    def structured_apply(schema, text, max_repairs = 0, repairer = nil)
+      StructuredOutput.new(schema: schema, max_repairs: max_repairs, repairer: repairer).apply(text)
+    end
+
+    def fallback_model(fallback)
+      lambda do |next_handler|
+        lambda do |request|
+          begin
+            next_handler.call(request)
+          rescue StandardError
+            raise unless fallback
+            fallback.call(request)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/praxo/models.rb

@@ -0,0 +1,154 @@
+module Praxo
+  module Models
+    SYSTEM = 'system'
+    USER = 'user'
+    ASSISTANT = 'assistant'
+    TOOL = 'tool'
+
+    STREAM_KINDS = %w[values updates messages tasks debug checkpoint].freeze
+
+    ContentBlock = Struct.new(:type, :text, :image_url, :data, keyword_init: true)
+    ToolCall = Struct.new(:id, :name, :arguments, keyword_init: true)
+    ToolSpec = Struct.new(:name, :description, :parameters, :risk, keyword_init: true)
+    Message = Struct.new(:role, :content, :content_blocks, :tool_calls, :tool_id, keyword_init: true)
+    Usage = Struct.new(:input_tokens, :output_tokens, :cached_tokens, keyword_init: true) do
+      def plus(other)
+        Usage.new(
+          input_tokens: input_tokens.to_i + other.input_tokens.to_i,
+          output_tokens: output_tokens.to_i + other.output_tokens.to_i,
+          cached_tokens: cached_tokens.to_i + other.cached_tokens.to_i
+        )
+      end
+    end
+    Request = Struct.new(:messages, :tools, :tool_choice, :response_format, :temperature, keyword_init: true)
+    Response = Struct.new(:message, :usage, :finish_reason, keyword_init: true)
+    Session = Struct.new(:id, :messages, keyword_init: true)
+    RunResult = Struct.new(:run_id, :output, :steps, :usage, keyword_init: true)
+    MemoryRecord = Struct.new(:id, :frame, :content, :created_at, keyword_init: true)
+    PathGrant = Struct.new(:root, :access, keyword_init: true)
+    Action = Struct.new(:kind, :session_id, :tool_name, :arguments, keyword_init: true)
+    Decision = Struct.new(:allowed, :reason, keyword_init: true)
+    Event = Struct.new(:type, :session_id, :run_id, :data, keyword_init: true)
+
+    module_function
+
+    def content_block(**args)
+      ContentBlock.new(
+        type: args[:type] || 'text',
+        text: args[:text],
+        image_url: args[:image_url],
+        data: args[:data]
+      )
+    end
+
+    def tool_call(**args)
+      ToolCall.new(
+        id: args[:id] || '',
+        name: args[:name] || '',
+        arguments: args[:arguments] || {}
+      )
+    end
+
+    def message(**args)
+      Message.new(
+        role: args[:role] || USER,
+        content: args[:content],
+        content_blocks: args[:content_blocks] || [],
+        tool_calls: args[:tool_calls] || [],
+        tool_id: args[:tool_id]
+      )
+    end
+
+    def message_text(role, content)
+      message(role: role, content: content)
+    end
+
+    def message_assistant(content, tool_calls = [])
+      message(role: ASSISTANT, content: content, tool_calls: tool_calls)
+    end
+
+    def message_tool(content, tool_id)
+      message(role: TOOL, content: content, tool_id: tool_id)
+    end
+
+    def tool_spec(**args)
+      ToolSpec.new(
+        name: args[:name] || '',
+        description: args[:description] || '',
+        parameters: args[:parameters],
+        risk: args[:risk]
+      )
+    end
+
+    def usage(input_tokens: 0, output_tokens: 0, cached_tokens: 0)
+      Usage.new(input_tokens: input_tokens, output_tokens: output_tokens,
+                cached_tokens: cached_tokens)
+    end
+
+    def request(**args)
+      Request.new(
+        messages: args[:messages] || [],
+        tools: args[:tools] || [],
+        tool_choice: args[:tool_choice],
+        response_format: args[:response_format],
+        temperature: args[:temperature] || 0
+      )
+    end
+
+    def response(message:, usage: nil, finish_reason: nil)
+      Response.new(message: message, usage: usage || Praxo::Models.usage,
+                   finish_reason: finish_reason)
+    end
+
+    def session(id:, messages: [])
+      Session.new(id: id, messages: messages)
+    end
+
+    def run_result(run_id:, output:, steps:, usage:)
+      RunResult.new(run_id: run_id, output: output, steps: steps, usage: usage)
+    end
+
+    def memory_record(**args)
+      MemoryRecord.new(
+        id: args[:id] || '',
+        frame: args[:frame] || '',
+        content: args[:content] || '',
+        created_at: args[:created_at]
+      )
+    end
+
+    def event(type:, session_id:, run_id: nil, data: nil)
+      Event.new(type: type, session_id: session_id, run_id: run_id, data: data)
+    end
+
+    def action(kind:, session_id:, tool_name: nil, arguments: nil)
+      Action.new(kind: kind, session_id: session_id, tool_name: tool_name,
+                 arguments: arguments)
+    end
+
+    def decision(allowed:, reason: '')
+      Decision.new(allowed: allowed, reason: reason)
+    end
+
+    def message_wire(message)
+      out = { 'role' => message.role }
+      out['content'] = message.content unless message.content.nil?
+      unless message.content_blocks.nil? || message.content_blocks.empty?
+        out['contentBlocks'] = message.content_blocks.map do |block|
+          wire = { 'type' => block.type }
+          wire['text'] = block.text unless block.text.nil?
+          wire['image_url'] = block.image_url unless block.image_url.nil?
+          wire['data'] = block.data unless block.data.nil?
+          wire
+        end
+      end
+      unless message.tool_calls.nil? || message.tool_calls.empty?
+        out['toolCalls'] = message.tool_calls.map do |call|
+          { 'id' => call.id, 'name' => call.name, 'arguments' => call.arguments }
+        end
+      end
+      out['toolId'] = message.tool_id unless message.tool_id.nil?
+      out
+    end
+  end
+end

data/lib/praxo/plugin.rb

@@ -0,0 +1,147 @@
+require_relative 'errors'
+require_relative 'json'
+
+module Praxo
+  module Plugin
+    PluginManifest = Struct.new(
+      :schema_version, :id, :version, :kind, :entrypoint, :protocol,
+      :capabilities, :permissions, :limits, :isolation, :health, keyword_init: true
+    )
+
+    KINDS = %w[
+      tool.provider.v1 model.provider.v1 policy.provider.v1
+      memory.provider.v1 sandbox.provider.v1
+    ].freeze
+    TOP_KEYS = %w[
+      schemaVersion id version kind entrypoint protocol capabilities permissions
+      limits isolation health signature sbom
+    ].freeze
+    ENTRYPOINT_KEYS = %w[type command module image args dir].freeze
+    PERMISSION_KEYS = %w[filesystem network env].freeze
+    LIMIT_KEYS = %w[memoryMB cpuMillis timeoutMs maxInflight].freeze
+    HEALTH_KEYS = %w[method intervalMs].freeze
+    SIGNATURE_KEYS = %w[algorithm keyId].freeze
+
+    module_function
+
+    def parse_manifest(raw)
+      Praxo.error('PLUGIN_INVALID', 'plugin: manifest is empty') if raw.nil? || raw.strip.empty?
+      begin
+        root = JSON.parse(raw)
+      rescue JSON::ParserError => e
+        Praxo.error('PLUGIN_INVALID', "plugin: manifest: #{e.message}")
+      end
+      Praxo.error('PLUGIN_INVALID', 'plugin: manifest must be an object') unless root.is_a?(Hash)
+      check_keys(root, TOP_KEYS, 'manifest')
+      schema_version = as_int(root['schemaVersion'], 'schemaVersion')
+      if schema_version != 1
+        Praxo.error('PLUGIN_INVALID',
+                    "plugin: manifest: schemaVersion = #{schema_version}, want 1")
+      end
+      id = as_string(root['id'], 'id')
+      unless id.match?(/\A(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\z/)
+        Praxo.error('PLUGIN_INVALID', "plugin: manifest: id #{id} is not reverse-DNS")
+      end
+      version = as_string(root['version'], 'version')
+      unless version.match?(/\A(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\z/)
+        Praxo.error('PLUGIN_INVALID', "plugin: manifest: version #{version} is not semver")
+      end
+      kind = as_string(root['kind'], 'kind')
+      unless KINDS.include?(kind)
+        Praxo.error('PLUGIN_INVALID', "plugin: manifest: kind #{kind} is not a known contract")
+      end
+      protocol = as_string(root['protocol'], 'protocol')
+      unless protocol == 'jsonrpc-2'
+        Praxo.error('PLUGIN_INVALID', "plugin: manifest: protocol = #{protocol}, want jsonrpc-2")
+      end
+      entrypoint = as_object(root['entrypoint'], 'entrypoint')
+      check_keys(entrypoint, ENTRYPOINT_KEYS, 'entrypoint')
+      entry_type = as_string(entrypoint['type'], 'entrypoint.type')
+      required = case entry_type
+                 when 'process' then 'command'
+                 when 'wasm' then 'module'
+                 when 'container' then 'image'
+                 else
+                   Praxo.error('PLUGIN_INVALID',
+                               "plugin: manifest: unknown entrypoint type #{entry_type}")
+                 end
+      unless text_present(entrypoint[required])
+        Praxo.error('PLUGIN_INVALID',
+                    "plugin: manifest: #{entry_type} entrypoint requires #{required}")
+      end
+      isolation = as_string(root['isolation'], 'isolation')
+      unless isolation == entry_type
+        Praxo.error('PLUGIN_INVALID',
+                    "plugin: manifest: isolation #{isolation} does not match entrypoint #{entry_type}")
+      end
+      permissions = as_object(root['permissions'], 'permissions')
+      check_keys(permissions, PERMISSION_KEYS, 'permissions')
+      limits = as_object(root['limits'], 'limits')
+      check_keys(limits, LIMIT_KEYS, 'limits')
+      limits.each do |key, value|
+        Praxo.error('PLUGIN_INVALID', 'plugin: manifest: limits must not be negative') if as_int(value, "limits.#{key}").negative?
+      end
+      health = as_object(root['health'], 'health')
+      check_keys(health, HEALTH_KEYS, 'health')
+      if root.key?('signature')
+        signature = as_object(root['signature'], 'signature')
+        check_keys(signature, SIGNATURE_KEYS, 'signature')
+        unless text_present(signature['algorithm']) && text_present(signature['keyId'])
+          Praxo.error('PLUGIN_INVALID',
+                      'plugin: manifest: signature requires algorithm and keyId')
+        end
+      end
+      capabilities = []
+      if root.key?('capabilities')
+        unless root['capabilities'].is_a?(Array)
+          Praxo.error('PLUGIN_INVALID', 'plugin: manifest: capabilities must be an array')
+        end
+        root['capabilities'].each do |item|
+          capability = as_string(item, 'capabilities')
+          Praxo.error('PLUGIN_INVALID', 'plugin: manifest: capability must not be empty') if capability.empty?
+          Praxo.error('PLUGIN_INVALID', 'plugin: manifest: duplicate capability') if capabilities.include?(capability)
+          capabilities << capability
+        end
+      end
+      PluginManifest.new(
+        schema_version: schema_version, id: id, version: version, kind: kind,
+        entrypoint: entrypoint, protocol: protocol, capabilities: capabilities,
+        permissions: permissions, limits: limits, isolation: isolation, health: health
+      )
+    end
+
+    def check_keys(value, allowed, where)
+      value.each_key do |key|
+        unless allowed.include?(key)
+          Praxo.error('PLUGIN_INVALID', "plugin: manifest: unknown field #{key} in #{where}")
+        end
+      end
+    end
+
+    def as_object(value, where)
+      return {} if value.nil?
+      unless value.is_a?(Hash)
+        Praxo.error('PLUGIN_INVALID', "plugin: manifest: #{where} must be an object")
+      end
+      value
+    end
+
+    def as_string(value, where)
+      unless value.is_a?(String)
+        Praxo.error('PLUGIN_INVALID', "plugin: manifest: #{where} must be a string")
+      end
+      value
+    end
+
+    def as_int(value, where)
+      unless value.is_a?(Numeric) && value.to_i == value
+        Praxo.error('PLUGIN_INVALID', "plugin: manifest: #{where} must be an integer")
+      end
+      value.to_i
+    end
+
+    def text_present(value)
+      value.is_a?(String) && !value.empty?
+    end
+  end
+end

data/lib/praxo/runtime.rb

@@ -0,0 +1,224 @@
+require_relative 'errors'
+require_relative 'json'
+require_relative 'models'
+
+module Praxo
+  module Runtime
+    class MultiSink
+      def initialize(sinks)
+        @sinks = sinks
+      end
+
+      def emit(event)
+        @sinks.each { |sink| sink.emit(event) }
+      end
+    end
+
+    class FilterSink
+      def initialize(sink, predicate)
+        @sink = sink
+        @predicate = predicate
+      end
+
+      def emit(event)
+        @sink.emit(event) if @predicate.call(event)
+      end
+    end
+
+    class MemoryStore
+      def initialize
+        @records = Hash.new { |hash, key| hash[key] = [] }
+        @sequence = 0
+      end
+
+      def put(session_id, record)
+        if record.id.nil? || record.id.empty?
+          record.id = "mem-#{(Time.now.to_f * 1000).to_i}-#{@sequence}"
+          @sequence += 1
+        end
+        if record.created_at.nil?
+          record.created_at = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+        end
+        @records[session_id] << record
+        record
+      end
+
+      def search(session_id, query, limit)
+        needle = query.to_s.strip.downcase
+        matches = @records[session_id].select do |record|
+          needle.empty? || record.content.to_s.downcase.include?(needle)
+        end
+        matches.sort_by! { |record| record.created_at.to_s }.reverse!
+        limit.positive? ? matches.first(limit) : matches
+      end
+    end
+
+    class CheckpointAllowlist
+      def initialize
+        @registered = {}
+      end
+
+      def register(type)
+        Praxo.error('CHECKPOINT_ERROR', 'checkpoint: type is required') if type.nil? || type.empty?
+        @registered[type] = true
+      end
+
+      def marshal(type, value)
+        unless @registered[type]
+          Praxo.error('CHECKPOINT_TYPE_NOT_ALLOWED',
+                      "checkpoint: payload type not allowed: #{type}")
+        end
+        Json.stringify({ 'type' => type, 'data' => value })
+      end
+
+      def unmarshal(data)
+        envelope = Json.parse(data)
+        Praxo.error('CHECKPOINT_ERROR', 'checkpoint: envelope must be an object') unless envelope.is_a?(Hash)
+        type = envelope['type'].is_a?(String) ? envelope['type'] : ''
+        unless @registered[type]
+          Praxo.error('CHECKPOINT_TYPE_NOT_ALLOWED',
+                      "checkpoint: payload type not allowed: #{type}")
+        end
+        envelope['data']
+      end
+    end
+
+    class PathChecker
+      def initialize(grants)
+        @grants = grants.map do |grant|
+          Models::PathGrant.new(root: resolve_path(grant.root), access: grant.access || 'read')
+        end
+      end
+
+      def check(target, need)
+        unless %w[read write readwrite].include?(need)
+          Praxo.error('POLICY_ERROR', 'policy: invalid access')
+        end
+        return Models::Decision.new(allowed: false, reason: 'no allowed roots') if @grants.empty?
+        resolved = resolve_path(target)
+        matched = nil
+        @grants.each do |grant|
+          next unless within?(grant.root, resolved)
+          matched = grant.root
+          return Models::Decision.new(allowed: true, reason: "path within #{grant.root}") if allows?(grant.access, need)
+        end
+        Models::Decision.new(allowed: false, reason: matched ? 'insufficient grant' : 'outside roots')
+      end
+
+      def allowed?(target, need)
+        check(target, need).allowed
+      rescue Error
+        false
+      end
+
+      private
+
+      def resolve_path(value)
+        absolute = File.expand_path(value.to_s)
+        return File.realpath(absolute) if File.exist?(absolute)
+        parent = File.dirname(absolute)
+        return absolute if parent == absolute
+        File.join(resolve_path(parent), File.basename(absolute))
+      rescue StandardError
+        absolute
+      end
+
+      def within?(root, target)
+        root = root.tr('\\', '/').sub(%r{/+\z}, '')
+        target = target.tr('\\', '/').sub(%r{/+\z}, '')
+        if RbConfig::CONFIG['host_os'].match?(/mswin|mingw|cygwin/)
+          root = root.downcase
+          target = target.downcase
+        end
+        target == root || target.start_with?("#{root}/")
+      end
+
+      def allows?(grant, need)
+        return true if need == 'read' && %w[read readwrite].include?(grant)
+        return true if need == 'write' && %w[write readwrite].include?(grant)
+        return true if need == 'readwrite' && grant == 'readwrite'
+        false
+      end
+    end
+
+    class ContextBudget
+      attr_reader :max_tokens, :keep_recent
+
+      def initialize(max_tokens: 0, keep_recent: 0)
+        @max_tokens = max_tokens
+        @keep_recent = keep_recent
+      end
+
+      def compact(messages)
+        max = @max_tokens
+        return [messages, true] if max <= 0 || Runtime.estimate_tokens(messages) <= max
+        system = []
+        rest = []
+        messages.each do |message|
+          if message.role == Models::SYSTEM
+            next if message.content.to_s.start_with?('[context compacted:')
+            system << message
+          else
+            rest << message
+          end
+        end
+        if Runtime.estimate_tokens(system) > max
+          return [[], false] if system.empty?
+          first = system[0].dup
+          first.content = Runtime.truncate_to_tokens(system[0].content.to_s, max - 4)
+          system = [first]
+          return [[], false] if Runtime.estimate_tokens(system) > max
+        end
+        keep = @keep_recent.positive? ? @keep_recent : 4
+        start = [rest.length - keep, 0].max
+        start -= 1 while start.positive? && rest[start].role == Models::TOOL
+        marker = Models.message_text(
+          Models::SYSTEM,
+          "[context compacted: #{start} older messages omitted]"
+        )
+        kept = rest[start..] || []
+        build = lambda do
+          output = system.dup
+          output << marker if start.positive?
+          output.concat(kept)
+          output
+        end
+        output = build.call
+        while Runtime.estimate_tokens(output) > max && kept.length > 1
+          break if kept[1].role == Models::TOOL
+          kept.shift
+          output = build.call
+        end
+        [output, Runtime.estimate_tokens(output) <= max]
+      end
+    end
+
+    module_function
+
+    def estimate_tokens(messages)
+      total = 0
+      messages.each do |message|
+        total += 4 + message.content.to_s.length / 4
+        total += message.tool_id.to_s.length / 4
+        (message.content_blocks || []).each do |block|
+          total += 4 + block.text.to_s.length / 4
+          total += block.image_url.to_s.length / 4
+          total += block.data.to_s.length / 4
+        end
+        (message.tool_calls || []).each do |call|
+          total += 4 + call.name.to_s.length / 4
+          total += Json.stringify(call.arguments || {}).length / 4
+        end
+      end
+      total
+    end
+
+    def truncate_to_tokens(value, tokens)
+      return '' if tokens <= 0
+      limit = tokens * 4
+      return value if value.length <= limit
+      return value[0, limit] if limit <= 16
+      "#{value[0, limit - 16]}\n[truncated]"
+    end
+  end
+end

data/lib/praxo/toolcall.rb

@@ -0,0 +1,96 @@
+require_relative 'json'
+
+module Praxo
+  module Toolcall
+    ParsedToolCall = Struct.new(
+      :call_id, :name, :input, :operation, :resource, :risk, :reason,
+      :idempotency_key, keyword_init: true
+    )
+
+    module_function
+
+    def parse_toolcall(content)
+      call = parse_json_call(content) || parse_xml(content) || parse_tag(content) ||
+             parse_plain(content)
+      return nil unless call
+      call.call_id = "tc-#{(Time.now.to_f * 1000).to_i}"
+      call
+    end
+
+    def strip_markup(content)
+      output = content.dup
+      output.gsub!(%r{<tool_call\s+name="[^"]+"\s*>.*?(?:</tool_call>|$)}m, '')
+      output.gsub!(%r{<tool_call_invoke>.*?(?:</tool_call_invoke>|$)}m, '')
+      output.gsub!(%r{<[a-zA-Z][\w-]*(?:\.[\w-]+)+>\s*\{.*?(?:</[a-zA-Z][\w.-]*>|$)}m, '')
+      output.gsub!(/\n{3,}/, "\n\n")
+      output.strip
+    end
+
+    def parse_input_json(raw)
+      begin
+        value = JSON.parse(raw.strip)
+        return value if value.is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+      escaped = raw.gsub('\\', '\\\\\\\\')
+      begin
+        value = JSON.parse(escaped.strip)
+        return value if value.is_a?(Hash)
+      rescue JSON::ParserError
+        return nil
+      end
+      nil
+    end
+
+    def parse_json_call(content)
+      value = JSON.parse(content)
+      return nil unless value.is_a?(Hash) && value['name'].is_a?(String) &&
+                        !value['name'].empty?
+      ParsedToolCall.new(
+        name: value['name'],
+        input: value['input'].is_a?(Hash) ? value['input'] : {},
+        operation: value['operation'] || '',
+        resource: value['resource'] || '',
+        risk: value['risk'] || '',
+        reason: value['reason'] || '',
+        idempotency_key: value['idempotency_key'] || ''
+      )
+    rescue JSON::ParserError
+      nil
+    end
+
+    def parse_xml(content)
+      match = nil
+      content.scan(%r{<tool_call\s+name="([^"]+)"\s*>\s*(.*?)\s*</tool_call>}m) do |name, raw|
+        match = [name, raw]
+      end
+      return nil unless match
+      input = parse_input_json(match[1])
+      return nil unless input
+      ParsedToolCall.new(name: match[0], input: input)
+    end
+
+    def parse_tag(content)
+      match = nil
+      content.scan(%r{<([a-zA-Z][\w-]*(?:\.[\w-]+)+)>\s*(\{.*?)\s*(?:</[a-zA-Z][\w.-]*>|$)}m) do |name, raw|
+        match = [name, raw]
+      end
+      return nil unless match
+      input = parse_input_json(match[1])
+      return nil unless input
+      ParsedToolCall.new(name: match[0], input: input)
+    end
+
+    def parse_plain(content)
+      match = nil
+      content.scan(/(?:^|\n)\s*([a-zA-Z][\w.-]*)\s+(\{.*\})\s*(?:\n|$)/m) do |name, raw|
+        match = [name, raw]
+      end
+      return nil unless match && match[0].include?('.')
+      input = parse_input_json(match[1])
+      return nil unless input
+      ParsedToolCall.new(name: match[0], input: input)
+    end
+  end
+end

data/lib/praxo.rb

@@ -0,0 +1,9 @@
+require_relative 'praxo/errors'
+require_relative 'praxo/json'
+require_relative 'praxo/models'
+require_relative 'praxo/toolcall'
+require_relative 'praxo/jsonschema'
+require_relative 'praxo/plugin'
+require_relative 'praxo/runtime'
+require_relative 'praxo/middleware'
+require_relative 'praxo/agent'

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: praxo-core
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- AxisVela
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Native Ruby Core for the PRAXO-CORE agent framework: tools, policy,
+  events, memory, context, middleware, checkpoints, and an agent loop.'
+email:
+- releases@axisvela.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- api/0.1.0.txt
+- lib/praxo.rb
+- lib/praxo/agent.rb
+- lib/praxo/errors.rb
+- lib/praxo/json.rb
+- lib/praxo/jsonschema.rb
+- lib/praxo/middleware.rb
+- lib/praxo/models.rb
+- lib/praxo/plugin.rb
+- lib/praxo/runtime.rb
+- lib/praxo/toolcall.rb
+homepage: https://axisvela.github.io/praxo-core/
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/axisvela/praxo-core
+  bug_tracker_uri: https://github.com/axisvela/praxo-core/issues
+  documentation_uri: https://axisvela.github.io/praxo-core/languages/ruby/
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Embeddable MIT-licensed agent framework for Ruby
+test_files: []