prompt_objects 0.5.0 → 0.7.0

data/lib/prompt_objects/execution/scheduler.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module PromptObjects
+  module Execution
+    # Thread-aware in-process scheduler. It owns admission, per-thread writer
+    # leases, worker slots, and cross-thread priority selection; Runner owns the
+    # execution lifecycle after a lease is granted.
+    class Scheduler
+      class RejectedError < StandardError; end
+      class ClosedError < StandardError; end
+
+      Entry = Data.define(:run, :ticket, :deadline, :enqueue_sequence, :options)
+
+      class Ticket
+        def initialize(run_id)
+          @run_id = run_id
+          @mutex = Mutex.new
+          @condition = ConditionVariable.new
+          @complete = false
+          @value = nil
+          @error = nil
+        end
+
+        attr_reader :run_id
+
+        def wait(timeout: nil)
+          deadline = timeout && monotonic_time + timeout
+          @mutex.synchronize do
+            until @complete
+              remaining = deadline && deadline - monotonic_time
+              raise Timeout::Error, "run #{@run_id} did not finish" if remaining && !remaining.positive?
+
+              @condition.wait(@mutex, remaining)
+            end
+            raise @error if @error
+
+            @value
+          end
+        end
+
+        def complete?
+          @mutex.synchronize { @complete }
+        end
+
+        def resolve(value)
+          finish(value: value)
+        end
+
+        def reject(error)
+          finish(error: error)
+        end
+
+        private
+
+        def finish(value: nil, error: nil)
+          @mutex.synchronize do
+            return if @complete
+
+            @value = value
+            @error = error
+            @complete = true
+            @condition.broadcast
+          end
+        end
+
+        def monotonic_time
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+
+      def initialize(worker_limit:, max_active_runs:, max_active_per_po:, max_queued_per_thread:,
+                     execute:, ready: nil, cancel_queued: nil)
+        raise ArgumentError, "max_active_runs must be positive" unless max_active_runs.positive?
+        raise ArgumentError, "max_active_per_po must be positive" unless max_active_per_po.positive?
+        raise ArgumentError, "max_queued_per_thread must be positive" unless max_queued_per_thread.positive?
+
+        @execute = execute
+        @ready = ready || ->(_run) { true }
+        @cancel_queued = cancel_queued
+        @max_active_runs = max_active_runs
+        @max_active_per_po = max_active_per_po
+        @max_queued_per_thread = max_queued_per_thread
+        @queues = Hash.new { |hash, key| hash[key] = [] }
+        @entries_by_run_id = {}
+        @running_tokens = {}
+        @active_po_counts = Hash.new(0)
+        @active_threads = {}
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @closed = false
+        @enqueue_sequence = 0
+        @workers = Array.new(worker_limit) { start_worker }
+        @deadline_monitor = start_deadline_monitor
+      end
+
+      def submit(run, deadline: nil, **options)
+        @mutex.synchronize do
+          raise ClosedError, "scheduler is closed" if @closed
+          return @entries_by_run_id.fetch(run.id).ticket if @entries_by_run_id.key?(run.id)
+          raise RejectedError, "workspace active-run limit reached" if @entries_by_run_id.size >= @max_active_runs
+
+          queue = @queues[run.thread_id]
+          if queue.size >= @max_queued_per_thread
+            raise RejectedError, "thread queue limit reached for #{run.thread_id}"
+          end
+
+          @enqueue_sequence += 1
+          ticket = Ticket.new(run.id)
+          entry = Entry.new(
+            run: run,
+            ticket: ticket,
+            deadline: deadline,
+            enqueue_sequence: @enqueue_sequence,
+            options: options.freeze
+          )
+          queue << entry
+          queue.sort_by! { |queued| [queued.run.turn_ordinal, queued.enqueue_sequence] }
+          @entries_by_run_id[run.id] = entry
+          @condition.broadcast
+          ticket
+        end
+      end
+
+      def cancel(run_id, reason: "cancelled")
+        queued = nil
+        token = nil
+        @mutex.synchronize do
+          entry = @entries_by_run_id[run_id]
+          return false unless entry
+
+          token = @running_tokens[run_id]
+          unless token
+            @queues[entry.run.thread_id].delete(entry)
+            cleanup_queue(entry.run.thread_id)
+            @entries_by_run_id.delete(run_id)
+            queued = entry
+          end
+          @condition.broadcast
+        end
+
+        if token
+          token.cancel(reason)
+        else
+          @cancel_queued&.call(queued.run, reason)
+          queued.ticket.resolve(:cancelled)
+        end
+        true
+      end
+
+      def queued_count
+        @mutex.synchronize { @queues.values.sum(&:size) }
+      end
+
+      def running_count
+        @mutex.synchronize { @running_tokens.size }
+      end
+
+      def ticket(run_id)
+        @mutex.synchronize { @entries_by_run_id[run_id]&.ticket }
+      end
+
+      # Execute a queued run on the caller's current capacity. This is used by
+      # a parent joining its child so a one-worker scheduler cannot deadlock
+      # with the parent waiting and the child unable to start.
+      def help(run_id)
+        entry, token = claim_queued(run_id)
+        return ticket(run_id) unless entry
+
+        execute(entry, token)
+        entry.ticket
+      end
+
+      def wake
+        @mutex.synchronize { @condition.broadcast }
+      end
+
+      def shutdown(wait: true)
+        queued = []
+        @mutex.synchronize do
+          return if @closed
+
+          @closed = true
+          queued = @queues.values.flatten
+          @queues.clear
+          queued.each { |entry| @entries_by_run_id.delete(entry.run.id) }
+          @running_tokens.each_value { |token| token.cancel("scheduler shutdown") }
+          @condition.broadcast
+        end
+        queued.each { |entry| entry.ticket.reject(ClosedError.new("scheduler shut down")) }
+        @workers.each(&:join) if wait
+        @deadline_monitor.join if wait
+      end
+
+      private
+
+      def start_worker
+        Thread.new do
+          Thread.current.name = "prompt-objects-scheduler" if Thread.current.respond_to?(:name=)
+          worker_loop
+        end
+      end
+
+      def start_deadline_monitor
+        Thread.new do
+          Thread.current.name = "prompt-objects-deadlines" if Thread.current.respond_to?(:name=)
+          @mutex.synchronize do
+            loop do
+              break if @closed
+
+              expire_queued_entries
+              @condition.wait(@mutex, next_deadline_wait)
+            end
+          end
+        end
+      end
+
+      def worker_loop
+        loop do
+          entry, token = next_entry
+          break unless entry
+
+          execute(entry, token)
+        end
+      end
+
+      def next_entry
+        @mutex.synchronize do
+          loop do
+            return [nil, nil] if @closed
+
+            expire_queued_entries
+            entry = runnable_heads.max_by do |candidate|
+              [candidate.run.priority, -candidate.enqueue_sequence]
+            end
+            if entry
+              queue = @queues[entry.run.thread_id]
+              queue.shift
+              cleanup_queue(entry.run.thread_id)
+              token = CancellationToken.new
+              @active_threads[entry.run.thread_id] = entry.run.id
+              @running_tokens[entry.run.id] = token
+              @active_po_counts[entry.run.po_name] += 1
+              return [entry, token]
+            end
+
+            @condition.wait(@mutex, next_deadline_wait)
+          end
+        end
+      end
+
+      def claim_queued(run_id)
+        @mutex.synchronize do
+          entry = @entries_by_run_id[run_id]
+          return [nil, nil] unless entry
+          return [nil, nil] if @running_tokens.key?(run_id)
+          return [nil, nil] if @active_threads.key?(entry.run.thread_id)
+          return [nil, nil] if po_at_capacity?(entry.run)
+          return [nil, nil] unless @ready.call(entry.run)
+
+          @queues[entry.run.thread_id].delete(entry)
+          cleanup_queue(entry.run.thread_id)
+          token = CancellationToken.new
+          @active_threads[entry.run.thread_id] = run_id
+          @running_tokens[run_id] = token
+          @active_po_counts[entry.run.po_name] += 1
+          [entry, token]
+        end
+      end
+
+      def runnable_heads
+        @queues.filter_map do |thread_id, queue|
+          next if queue.empty? || @active_threads.key?(thread_id)
+
+          head = queue.first
+          head if !po_at_capacity?(head.run) && @ready.call(head.run)
+        end
+      end
+
+      def expire_queued_entries
+        now = Time.now
+        expired = @queues.values.flatten.select { |entry| entry.deadline && entry.deadline <= now }
+        expired.each do |entry|
+          @queues[entry.run.thread_id].delete(entry)
+          cleanup_queue(entry.run.thread_id)
+          @entries_by_run_id.delete(entry.run.id)
+          @cancel_queued&.call(entry.run, "deadline exceeded")
+          entry.ticket.resolve(:cancelled)
+        end
+      end
+
+      def next_deadline_wait
+        deadline = @queues.values.flatten.filter_map(&:deadline).min
+        return nil unless deadline
+
+        [deadline - Time.now, 0].max
+      end
+
+      def execute(entry, token)
+        value = @execute.call(entry.run, token, entry.options)
+        entry.ticket.resolve(value)
+      rescue => e
+        entry.ticket.reject(e)
+      ensure
+        @mutex.synchronize do
+          @running_tokens.delete(entry.run.id)
+          @active_threads.delete(entry.run.thread_id)
+          @active_po_counts[entry.run.po_name] -= 1
+          @active_po_counts.delete(entry.run.po_name) unless @active_po_counts[entry.run.po_name].positive?
+          @entries_by_run_id.delete(entry.run.id)
+          @condition.broadcast
+        end
+      end
+
+      def cleanup_queue(thread_id)
+        @queues.delete(thread_id) if @queues[thread_id].empty?
+      end
+
+      def po_at_capacity?(run)
+        @active_po_counts[run.po_name] >= @max_active_per_po
+      end
+    end
+  end
+end

data/lib/prompt_objects/llm/factory.rb

@@ -12,8 +12,8 @@ module PromptObjects
         "openai" => {
           adapter: "OpenAIAdapter",
           env_key: "OPENAI_API_KEY",
-          default_model: "gpt-5.2",
-          models: %w[gpt-5.2 gpt-4.1 gpt-4.1-mini gpt-4.5-preview o3-mini o1]
+          default_model: "gpt-5.6-luna",
+          models: %w[gpt-5.6-luna gpt-5.6-terra gpt-5.6-sol gpt-5.4-mini gpt-5.4-nano gpt-5.2 gpt-4.1 gpt-4.1-mini]
         },
         "anthropic" => {
           adapter: "AnthropicAdapter",
@@ -24,8 +24,8 @@ module PromptObjects
         "gemini" => {
           adapter: "GeminiAdapter",
           env_key: "GEMINI_API_KEY",
-          default_model: "gemini-3-flash-preview",
-          models: %w[gemini-3-flash-preview gemini-2.5-pro gemini-2.5-flash]
+          default_model: "gemini-3.5-flash",
+          models: %w[gemini-3.5-flash gemini-3.1-flash-lite gemini-3-flash-preview gemini-2.5-pro gemini-2.5-flash]
         },
         "ollama" => {
           adapter: "OpenAIAdapter",

data/lib/prompt_objects/llm/gemini_adapter.rb

@@ -10,7 +10,7 @@ module PromptObjects
     # Google Gemini API adapter for LLM calls.
     # Uses direct HTTP calls to the Gemini REST API.
     class GeminiAdapter
-      DEFAULT_MODEL = "gemini-3-flash-preview"
+      DEFAULT_MODEL = "gemini-3.5-flash"
       API_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
 
       def initialize(api_key: nil, model: nil)
@@ -72,14 +72,22 @@ module PromptObjects
                 tc_id = tc.respond_to?(:id) ? tc.id : (tc[:id] || tc["id"])
                 tc_name = tc.respond_to?(:name) ? tc.name : (tc[:name] || tc["name"])
                 tc_args = tc.respond_to?(:arguments) ? tc.arguments : (tc[:arguments] || tc["arguments"] || {})
+                tc_metadata = if tc.respond_to?(:provider_metadata)
+                                tc.provider_metadata
+                              else
+                                tc[:provider_metadata] || tc["provider_metadata"] || {}
+                              end
 
                 last_tool_calls[tc_id] = tc_name
-                parts << {
+                function_part = {
                   functionCall: {
                     name: tc_name,
                     args: tc_args
                   }
                 }
+                thought_signature = tc_metadata[:thought_signature] || tc_metadata["thought_signature"]
+                function_part[:thoughtSignature] = thought_signature if thought_signature
+                parts << function_part
               end
             end
             result << { role: "model", parts: parts } if parts.any?
@@ -103,15 +111,19 @@ module PromptObjects
       end
 
       def parse_tool_response_content(content)
-        # Try to parse as JSON, otherwise wrap in a result object
+        # Gemini's functionResponse.response must always be a Struct/object.
+        # Preserve JSON objects directly and wrap scalars, arrays, and text.
         if content.is_a?(String)
           begin
-            JSON.parse(content)
+            parsed = JSON.parse(content)
+            parsed.is_a?(Hash) ? parsed : { result: parsed }
           rescue JSON::ParserError
             { result: content }
           end
-        else
+        elsif content.is_a?(Hash)
           content
+        else
+          { result: content }
         end
       end
 
@@ -188,7 +200,7 @@ module PromptObjects
           if part["text"]
             text_content += part["text"]
           elsif part["functionCall"]
-            tool_calls << parse_function_call(part["functionCall"])
+            tool_calls << parse_function_call(part)
           end
         end
 
@@ -207,13 +219,18 @@ module PromptObjects
         }
       end
 
-      def parse_function_call(fc)
+      def parse_function_call(part)
+        fc = part["functionCall"]
+        provider_metadata = {}
+        provider_metadata[:thought_signature] = part["thoughtSignature"] if part["thoughtSignature"]
+
         # Gemini doesn't use tool_call_id like OpenAI, so we generate one
         # based on the function name and a random suffix
         ToolCall.new(
           id: "call_#{fc['name']}_#{SecureRandom.hex(8)}",
           name: fc["name"],
-          arguments: fc["args"] || {}
+          arguments: fc["args"] || {},
+          provider_metadata: provider_metadata
         )
       end
     end

data/lib/prompt_objects/llm/openai_adapter.rb

@@ -4,7 +4,7 @@ module PromptObjects
   module LLM
     # OpenAI API adapter for LLM calls.
     class OpenAIAdapter
-      DEFAULT_MODEL = "gpt-5.2"
+      DEFAULT_MODEL = "gpt-5.6-luna"
 
       def initialize(api_key: nil, model: nil, base_url: nil, extra_headers: nil, provider_name: nil)
         @api_key = api_key || ENV.fetch("OPENAI_API_KEY") do
@@ -34,6 +34,10 @@ module PromptObjects
         if tools.any?
           params[:tools] = tools
           params[:tool_choice] = "auto"
+          # GPT-5.6 supports function tools through Chat Completions only when
+          # reasoning is disabled. Other OpenAI-compatible providers may not
+          # recognize this parameter, so keep the compatibility fix narrow.
+          params[:reasoning_effort] = "none" if openai_gpt_5_6?
         end
 
         raw_response = @client.chat(parameters: params)
@@ -64,6 +68,10 @@ module PromptObjects
 
       private
 
+      def openai_gpt_5_6?
+        @provider_name == "openai" && @model.start_with?("gpt-5.6")
+      end
+
       def build_messages(system, messages)
         result = [{ role: "system", content: system }]
 

data/lib/prompt_objects/llm/pricing.rb

@@ -8,6 +8,11 @@ module PromptObjects
     class Pricing
       RATES = {
         # OpenAI
+        "gpt-5.6-sol" => { input: 5.00, output: 30.00 },
+        "gpt-5.6-terra" => { input: 2.50, output: 15.00 },
+        "gpt-5.6-luna" => { input: 1.00, output: 6.00 },
+        "gpt-5.4-mini" => { input: 0.75, output: 4.50 },
+        "gpt-5.4-nano" => { input: 0.20, output: 1.25 },
         "gpt-5.2" => { input: 2.00, output: 8.00 },
         "gpt-4.1" => { input: 2.00, output: 8.00 },
         "gpt-4.1-mini" => { input: 0.40, output: 1.60 },
@@ -19,9 +24,11 @@ module PromptObjects
         "claude-sonnet-4-5" => { input: 3.00, output: 15.00 },
         "claude-haiku-4-5" => { input: 1.00, output: 5.00 },
         # Gemini
-        "gemini-3-flash-preview" => { input: 0.15, output: 0.60 },
+        "gemini-3.5-flash" => { input: 1.50, output: 9.00 },
+        "gemini-3.1-flash-lite" => { input: 0.25, output: 1.50 },
+        "gemini-3-flash-preview" => { input: 0.50, output: 3.00 },
         "gemini-2.5-pro" => { input: 1.25, output: 10.00 },
-        "gemini-2.5-flash" => { input: 0.15, output: 0.60 },
+        "gemini-2.5-flash" => { input: 0.30, output: 2.50 },
       }.freeze
 
       # Calculate cost in USD for a given usage.

data/lib/prompt_objects/llm/response.rb

@@ -25,12 +25,13 @@ module PromptObjects
     # Supports both method access (.id) and hash access ([:id]) for compatibility
     # with code that may receive either ToolCall objects or Hashes from the DB.
     class ToolCall
-      attr_reader :id, :name, :arguments
+      attr_reader :id, :name, :arguments, :provider_metadata
 
-      def initialize(id:, name:, arguments:)
+      def initialize(id:, name:, arguments:, provider_metadata: nil)
         @id = id
         @name = name
         @arguments = arguments
+        @provider_metadata = provider_metadata || {}
       end
 
       # Allow hash-style access for compatibility with code expecting Hashes
@@ -39,12 +40,15 @@ module PromptObjects
         when :id then @id
         when :name then @name
         when :arguments then @arguments
+        when :provider_metadata then @provider_metadata
         end
       end
 
       # Convert to a plain Hash (for serialization)
       def to_h
-        { id: @id, name: @name, arguments: @arguments }
+        result = { id: @id, name: @name, arguments: @arguments }
+        result[:provider_metadata] = @provider_metadata unless @provider_metadata.empty?
+        result
       end
 
       # Create a ToolCall from a Hash (for deserialization)
@@ -54,7 +58,8 @@ module PromptObjects
         new(
           id: hash[:id] || hash["id"],
           name: hash[:name] || hash["name"],
-          arguments: hash[:arguments] || hash["arguments"] || {}
+          arguments: hash[:arguments] || hash["arguments"] || {},
+          provider_metadata: hash[:provider_metadata] || hash["provider_metadata"] || {}
         )
       end
     end

data/lib/prompt_objects/loader.rb

@@ -11,15 +11,42 @@ module PromptObjects
       raise Error, "File not found: #{path}" unless File.exist?(path)
 
       content = File.read(path, encoding: "UTF-8")
+      parse(content, path: path)
+    end
+
+    # Parse prompt object markdown from a raw string (frontmatter + body).
+    # Raises if the YAML frontmatter is malformed, so callers can validate
+    # before persisting (see PromptObject#update_source).
+    # @param content [String] Raw .md content
+    # @param path [String, nil] Source path to record in the result
+    # @return [Hash] Parsed data with :config, :body, and :path
+    def self.parse(content, path: nil)
       parsed = FrontMatterParser::Parser.new(:md).call(content)
+      config = parsed.front_matter || {}
+
+      # Merge simplified frontmatter (delegates_to + tools) into capabilities.
+      # This lets PO authors distinguish PO references from primitive references
+      # while keeping the internal model uniform.
+      merge_capabilities(config)
 
       {
-        config: parsed.front_matter || {},
+        config: config,
         body: parsed.content.strip,
         path: path
       }
     end
 
+    # Merge delegates_to + tools into the capabilities array.
+    # If both new-style and old-style keys are present, they are combined.
+    def self.merge_capabilities(config)
+      delegates = config.delete("delegates_to") || []
+      tools = config.delete("tools") || []
+      return if delegates.empty? && tools.empty?
+
+      existing = config["capabilities"] || []
+      config["capabilities"] = (existing + delegates + tools).uniq
+    end
+
     # Load all prompt objects from a directory.
     # @param dir [String] Directory path
     # @return [Array<Hash>] Array of parsed prompt objects

data/lib/prompt_objects/mcp/server.rb

@@ -100,9 +100,12 @@ module PromptObjects
         po = @env.registry.get(po_name)
         return [{ uri: "po://#{po_name}/conversation", mimeType: "text/plain", text: "PO not found" }] unless po
 
-        history = po.history.map do |msg|
-          { role: msg[:role].to_s, content: msg[:content] }
-        end
+        workspace_id = @env.active_session(initiated_by: "service:mcp")[:id]
+        thread = Repositories::ThreadRepository.new(@env.session_store)
+          .list(workspace_session_id: workspace_id, po_name: po_name).last
+        history = thread ? Repositories::MessageRepository.new(@env.session_store)
+          .list(thread_id: thread.id, limit: 10_000)
+          .map { |message| { role: message[:role].to_s, content: message[:content] } } : []
 
         [{
           uri: "po://#{po_name}/conversation",

data/lib/prompt_objects/mcp/tools/get_conversation.rb

@@ -18,12 +18,16 @@ module PromptObjects
             limit: {
               type: "integer",
               description: "Maximum number of messages to return (default: all)"
+            },
+            thread_id: {
+              type: "string",
+              description: "Optional runtime thread ID"
             }
           },
           required: %w[po_name]
         )
 
-        def self.call(po_name:, limit: nil, server_context:)
+        def self.call(po_name:, limit: nil, thread_id: nil, server_context:)
           env = server_context[:env]
 
           po = env.registry.get(po_name)
@@ -34,21 +38,21 @@ module PromptObjects
             }])
           end
 
-          history = po.history.map do |msg|
-            {
-              role: msg[:role].to_s,
-              content: msg[:content],
-              from: msg[:from],
-              tool_calls: msg[:tool_calls]&.map { |tc| { name: tc.name, arguments: tc.arguments } }
-            }.compact
-          end
-
-          history = history.last(limit) if limit
+          workspace_id = env.active_session(initiated_by: "service:mcp")[:id]
+          threads = Repositories::ThreadRepository.new(env.session_store)
+            .list(workspace_session_id: workspace_id, po_name: po_name)
+          thread = thread_id ? threads.find { |candidate| candidate.id == thread_id } : threads.last
+          history = thread ? Repositories::MessageRepository.new(env.session_store)
+            .list(thread_id: thread.id, limit: limit || 10_000)
+            .map do |message|
+              { role: message[:role].to_s, content: message[:content], from: message[:from_po] }.compact
+            end : []
 
           ::MCP::Tool::Response.new([{
             type: "text",
             text: JSON.pretty_generate({
               po_name: po_name,
+              thread_id: thread&.id,
               message_count: history.length,
               history: history
             })

data/lib/prompt_objects/mcp/tools/get_pending_requests.rb

@@ -3,10 +3,10 @@
 module PromptObjects
   module MCP
     module Tools
-      # Get all pending human requests from the queue
+      # Get pending capability-approval requests from the queue.
       class GetPendingRequests < ::MCP::Tool
         tool_name "get_pending_requests"
-        description "Get all pending human requests across all prompt objects. These are questions POs have asked that await human response."
+        description "Get pending capability-approval requests that await a response."
 
         input_schema(
           type: "object",

data/lib/prompt_objects/mcp/tools/respond_to_request.rb

@@ -3,10 +3,10 @@
 module PromptObjects
   module MCP
     module Tools
-      # Respond to a pending human request
+      # Respond to a pending capability-approval request.
       class RespondToRequest < ::MCP::Tool
         tool_name "respond_to_request"
-        description "Respond to a pending human request from a prompt object. This unblocks the PO that asked the question."
+        description "Respond to a pending capability-approval request."
 
         input_schema(
           type: "object",
@@ -48,7 +48,7 @@ module PromptObjects
           env.bus.publish(
             from: "mcp_client",
             to: request.capability,
-            message: "[response to ask_human] #{response}"
+            message: "[response to pending request] #{response}"
           )
 
           ::MCP::Tool::Response.new([{