prompt_objects 0.5.0 → 0.7.0

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

@@ -18,15 +18,30 @@ module PromptObjects
             message: {
               type: "string",
               description: "The message to send"
+            },
+            thread_id: {
+              type: "string",
+              description: "Optional runtime thread ID"
+            },
+            workspace_session_id: {
+              type: "string",
+              description: "Optional workspace session ID"
+            },
+            client_request_id: {
+              type: "string",
+              description: "Optional idempotency key"
+            },
+            deadline: {
+              type: "string",
+              description: "Optional ISO 8601 deadline for queued and running work"
             }
           },
           required: %w[po_name message]
         )
 
-        def self.call(po_name:, message:, server_context:)
+        def self.call(po_name:, message:, thread_id: nil, workspace_session_id: nil,
+                      client_request_id: nil, deadline: nil, server_context:)
           env = server_context[:env]
-          context = server_context[:context]
-
           po = env.registry.get(po_name)
           unless po.is_a?(PromptObjects::PromptObject)
             return ::MCP::Tool::Response.new([{
@@ -35,35 +50,30 @@ module PromptObjects
             }])
           end
 
-          # Log to message bus
-          env.bus.publish(from: "mcp_client", to: po_name, message: message)
-
-          # Set context for this interaction
-          context.current_capability = po_name
-          po.state = :working
-
-          begin
-            response = po.receive(message, context: context)
-            po.state = :idle
-
-            # Log response
-            env.bus.publish(from: po_name, to: "mcp_client", message: response)
-
-            ::MCP::Tool::Response.new([{
-              type: "text",
-              text: JSON.generate({
-                po_name: po_name,
-                response: response,
-                history_length: po.history.length
-              })
-            }])
-          rescue StandardError => e
-            po.state = :idle
-            ::MCP::Tool::Response.new([{
-              type: "text",
-              text: JSON.generate({ error: e.message, backtrace: e.backtrace.first(5) })
-            }])
-          end
+          run, response = env.execute_message_run(
+            target_po: po_name,
+            content: message,
+            from_source: "service:mcp",
+            workspace_session_id: workspace_session_id,
+            thread_id: thread_id,
+            client_request_id: client_request_id,
+            deadline: deadline,
+            tui_mode: true
+          )
+          history_length = Repositories::MessageRepository.new(env.session_store)
+            .list(thread_id: run.thread_id, limit: 10_000).length
+          ::MCP::Tool::Response.new([{
+            type: "text",
+            text: JSON.generate({
+              po_name: po_name,
+              response: response,
+              workspace_session_id: run.workspace_session_id,
+              thread_id: run.thread_id,
+              run_id: run.id,
+              status: run.status,
+              history_length: history_length
+            })
+          }])
         end
       end
     end

data/lib/prompt_objects/operations/diagnostics.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Operations
+    # Content-free operational snapshot for health checks and support bundles.
+    class Diagnostics
+      TABLES = %w[
+        workspace_sessions sessions runs messages run_events workspace_events
+        tool_executions artifacts env_data
+      ].freeze
+
+      def initialize(store)
+        @store = store
+      end
+
+      def snapshot(scheduler: {}, limits: {})
+        data = @store.with_connection do |db|
+          runs = db.execute(<<~SQL)
+            SELECT status, provider, model, enqueued_at, started_at, finished_at, usage
+            FROM runs
+          SQL
+          tools = db.execute("SELECT status, started_at, finished_at FROM tool_executions")
+          {
+            schema_version: db.get_first_value("PRAGMA user_version").to_i,
+            database: database_stats(db),
+            counts: TABLES.to_h { |table| [table.to_sym, db.get_first_value("SELECT COUNT(*) FROM #{table}").to_i] },
+            runs: run_stats(runs),
+            tools: tool_stats(tools)
+          }
+        end
+        data.merge(
+          generated_at: Time.now.utc.iso8601,
+          scheduler: scheduler,
+          limits: limits
+        )
+      end
+
+      private
+
+      def database_stats(db)
+        path = db.execute("PRAGMA database_list").find { |row| row["name"] == "main" }&.dig("file")
+        files = [path, "#{path}-wal", "#{path}-shm"].compact
+        {
+          filename: path && File.basename(path),
+          bytes: files.sum { |file| File.file?(file) ? File.size(file) : 0 },
+          journal_mode: db.get_first_value("PRAGMA journal_mode"),
+          integrity: db.get_first_value("PRAGMA quick_check")
+        }
+      end
+
+      def run_stats(rows)
+        status_counts = rows.group_by { |row| row["status"] }.transform_values(&:length)
+        terminal = rows.count { |row| %w[completed failed cancelled skipped interrupted].include?(row["status"]) }
+        failures = rows.count { |row| %w[failed interrupted].include?(row["status"]) }
+        {
+          by_status: status_counts,
+          active: rows.count { |row| %w[queued running waiting].include?(row["status"]) },
+          failure_rate: terminal.zero? ? 0.0 : (failures.to_f / terminal).round(4),
+          queue_wait_ms: duration_stats(rows, "enqueued_at", "started_at"),
+          duration_ms: duration_stats(rows, "started_at", "finished_at"),
+          provider_usage: provider_usage(rows)
+        }
+      end
+
+      def tool_stats(rows)
+        {
+          by_status: rows.group_by { |row| row["status"] }.transform_values(&:length),
+          duration_ms: duration_stats(rows, "started_at", "finished_at")
+        }
+      end
+
+      def duration_stats(rows, start_key, finish_key)
+        values = rows.filter_map do |row|
+          next unless row[start_key] && row[finish_key]
+
+          ((Time.parse(row[finish_key]) - Time.parse(row[start_key])) * 1000).round(2)
+        end.sort
+        return { count: 0, average: 0.0, p95: 0.0, maximum: 0.0 } if values.empty?
+
+        {
+          count: values.length,
+          average: (values.sum / values.length.to_f).round(2),
+          p95: values[[(values.length * 0.95).ceil - 1, 0].max],
+          maximum: values.last
+        }
+      end
+
+      def provider_usage(rows)
+        rows.group_by { |row| [row["provider"] || "unknown", row["model"] || "unknown"] }
+          .to_h do |(provider, model), provider_rows|
+            usage = provider_rows.filter_map { |row| parse_json(row["usage"]) }
+            [[provider, model].join("/"), {
+              runs: provider_rows.length,
+              input_tokens: usage.sum { |value| token_value(value, :input_tokens, :prompt_tokens) },
+              output_tokens: usage.sum { |value| token_value(value, :output_tokens, :completion_tokens) }
+            }]
+          end
+      end
+
+      def parse_json(value)
+        value && JSON.parse(value, symbolize_names: true)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def token_value(usage, *keys)
+        keys.each do |key|
+          value = usage[key]
+          return value.to_i if value
+        end
+        0
+      end
+    end
+  end
+end

data/lib/prompt_objects/operations/retention.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Operations
+    # Bounds replay logs while preserving current snapshots and durable domain
+    # rows. Pruned clients recover from workspace/thread snapshots.
+    class Retention
+      DEFAULT_RUN_EVENT_LIMIT = 500
+      DEFAULT_WORKSPACE_EVENT_LIMIT = 5_000
+
+      def initialize(store)
+        @store = store
+      end
+
+      def prune_events!(run_event_limit: DEFAULT_RUN_EVENT_LIMIT,
+                        workspace_event_limit: DEFAULT_WORKSPACE_EVENT_LIMIT)
+        raise ArgumentError, "run_event_limit must be positive" unless run_event_limit.positive?
+        raise ArgumentError, "workspace_event_limit must be positive" unless workspace_event_limit.positive?
+
+        @store.transaction do |db|
+          run_event_ids = db.execute(<<~SQL, [run_event_limit]).map { |row| row["id"] }
+            SELECT id FROM (
+              SELECT id, ROW_NUMBER() OVER (PARTITION BY run_id ORDER BY sequence DESC) AS position
+              FROM run_events
+            ) WHERE position > ?
+          SQL
+          workspace_cursors = run_event_ids.empty? ? [] : db.execute(
+            "SELECT workspace_cursor FROM run_events WHERE id IN (#{placeholders(run_event_ids)})",
+            run_event_ids
+          ).map { |row| row["workspace_cursor"] }
+          delete_ids(db, "run_events", run_event_ids)
+          delete_ids(db, "workspace_events", workspace_cursors)
+
+          workspace_event_ids = db.execute(<<~SQL, [workspace_event_limit]).map { |row| row["id"] }
+            SELECT id FROM (
+              SELECT id, ROW_NUMBER() OVER (
+                PARTITION BY workspace_session_id ORDER BY id DESC
+              ) AS position
+              FROM workspace_events
+            ) WHERE position > ?
+          SQL
+          workspace_event_ids.reject! do |id|
+            db.get_first_value("SELECT 1 FROM run_events WHERE workspace_cursor = ?", [id])
+          end
+          delete_ids(db, "workspace_events", workspace_event_ids)
+
+          {
+            run_events_deleted: run_event_ids.length,
+            workspace_events_deleted: (workspace_cursors + workspace_event_ids).uniq.length
+          }
+        end
+      end
+
+      def compact!
+        @store.with_connection do |db|
+          db.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+          db.execute("VACUUM")
+        end
+        true
+      end
+
+      private
+
+      def delete_ids(db, table, ids)
+        return if ids.empty?
+
+        db.execute("DELETE FROM #{table} WHERE id IN (#{placeholders(ids)})", ids)
+      end
+
+      def placeholders(values)
+        Array.new(values.length, "?").join(", ")
+      end
+    end
+  end
+end

data/lib/prompt_objects/operations/run_trace_builder.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Operations
+    # Projects the durable runtime records for one execution tree into a
+    # debugger-friendly read model. The projection deliberately labels model
+    # context as reconstructed until exact provider exchanges are persisted.
+    class RunTraceBuilder
+      CATEGORY_BY_KIND = {
+        "model_started" => "model",
+        "model_completed" => "model",
+        "tool_batch_started" => "tool_batch",
+        "tool_started" => "tool",
+        "tool_completed" => "tool",
+        "tool_failed" => "tool",
+        "tool_cancelled" => "tool",
+        "delegation_started" => "delegation",
+        "delegation_completed" => "delegation",
+        "artifact_upserted" => "state",
+        "env_data_changed" => "state"
+      }.freeze
+
+      def initialize(store)
+        @runs = Repositories::RunRepository.new(store)
+        @definitions = Repositories::DefinitionRepository.new(store)
+        @messages = Repositories::MessageRepository.new(store)
+        @events = Repositories::EventRepository.new(store)
+        @tools = Repositories::ToolExecutionRepository.new(store)
+        @artifacts = Repositories::ArtifactRepository.new(store)
+      end
+
+      def build(run_id)
+        requested = @runs.get(run_id)
+        raise ArgumentError, "unknown run: #{run_id}" unless requested
+
+        root_run_id = requested.root_run_id || requested.id
+        related_runs = @runs.tree(root_run_id: root_run_id)
+        workspace_artifacts = @artifacts.list(workspace_session_id: requested.workspace_session_id)
+
+        {
+          requested_run_id: requested.id,
+          root_run_id: root_run_id,
+          workspace_session_id: requested.workspace_session_id,
+          completeness: {
+            run_records: "exact",
+            definitions: "exact_when_available",
+            messages: "exact",
+            tools: "exact",
+            model_context: "reconstructed",
+            state_history: "current_revision_only"
+          },
+          runs: related_runs.map { |run| build_run(run, related_runs, workspace_artifacts) }
+        }
+      end
+
+      private
+
+      def build_run(run, related_runs, workspace_artifacts)
+        events = @events.run_events(run_id: run.id)
+        tools = @tools.list(run_id: run.id)
+        definition = @definitions.get(run.id)
+        context_messages = @messages.list(
+          thread_id: run.thread_id,
+          through_turn: run.turn_ordinal,
+          limit: 10_000
+        )
+        run_messages = context_messages.select { |message| message[:run_id] == run.id }
+        produced_artifacts = workspace_artifacts.select { |artifact| artifact.producing_run_id == run.id }
+
+        {
+          run: run.to_h,
+          definition: definition&.to_h,
+          completeness: {
+            definition: definition ? "exact" : "unavailable",
+            model_context: "reconstructed",
+            state_history: produced_artifacts.empty? ? "unavailable" : "current_revision_only"
+          },
+          context_messages: context_messages,
+          messages: run_messages,
+          tool_executions: tools.map(&:to_h),
+          artifacts: produced_artifacts.map(&:to_h),
+          nodes: events.map do |event|
+            build_node(event, tools, related_runs, produced_artifacts)
+          end
+        }
+      end
+
+      def build_node(event, tools, related_runs, artifacts)
+        tool = tool_for(event, tools)
+        child = child_for(event, related_runs)
+        artifact = artifact_for(event, artifacts)
+        {
+          id: "#{event.run_id}:#{event.sequence}",
+          run_id: event.run_id,
+          sequence: event.sequence,
+          workspace_cursor: event.workspace_cursor,
+          kind: event.kind,
+          category: category_for(event.kind),
+          title: title_for(event, tool, child, artifact),
+          status: status_for(event.kind),
+          timestamp: event.timestamp,
+          data: event.data,
+          tool_execution: tool&.to_h,
+          child_run: child&.to_h,
+          artifact: artifact&.to_h
+        }
+      end
+
+      def tool_for(event, tools)
+        execution_id = event.data[:tool_execution_id] || event.data["tool_execution_id"]
+        tools.find { |tool| tool.id == execution_id }
+      end
+
+      def child_for(event, related_runs)
+        child_run_id = event.data[:child_run_id] || event.data["child_run_id"]
+        related_runs.find { |run| run.id == child_run_id }
+      end
+
+      def artifact_for(event, artifacts)
+        artifact_id = event.data[:artifact_id] || event.data["artifact_id"]
+        artifacts.find { |artifact| artifact.id == artifact_id }
+      end
+
+      def category_for(kind)
+        CATEGORY_BY_KIND.fetch(kind, "lifecycle")
+      end
+
+      def status_for(kind)
+        return "failed" if kind.end_with?("_failed")
+        return "cancelled" if kind.end_with?("_cancelled") || kind.end_with?("_interrupted")
+        return "completed" if kind.end_with?("_completed") || kind == "artifact_upserted"
+        return "active" if kind.end_with?("_started") || kind.end_with?("_waiting")
+
+        "info"
+      end
+
+      def title_for(event, tool, child, artifact)
+        case event.kind
+        when "tool_started", "tool_completed", "tool_failed", "tool_cancelled"
+          [event.kind.tr("_", " "), tool&.capability_name || event.data[:name]].compact.join(" · ")
+        when "delegation_started", "delegation_completed"
+          target = child&.po_name || event.data[:target_po] || event.data["target_po"]
+          [event.kind.tr("_", " "), target].compact.join(" · ")
+        when "artifact_upserted"
+          ["artifact upserted", artifact&.title || event.data[:title] || event.data["title"]].compact.join(" · ")
+        else
+          event.kind.tr("_", " ")
+        end
+      end
+    end
+  end
+end

data/lib/prompt_objects/primitives/http_get.rb

@@ -7,6 +7,8 @@ module PromptObjects
   module Primitives
     # Primitive capability to fetch content from a URL.
     class HttpGet < Primitive
+      execution_policy parallel_safe: true, side_effect: :read
+
       def name
         "http_get"
       end

data/lib/prompt_objects/primitives/list_files.rb

@@ -4,6 +4,8 @@ module PromptObjects
   module Primitives
     # Primitive capability to list files in a directory.
     class ListFiles < Primitive
+      execution_policy parallel_safe: true, side_effect: :read
+
       def name
         "list_files"
       end

data/lib/prompt_objects/primitives/read_file.rb

@@ -4,6 +4,8 @@ module PromptObjects
   module Primitives
     # Primitive capability to read file contents.
     class ReadFile < Primitive
+      execution_policy parallel_safe: true, side_effect: :read
+
       def name
         "read_file"
       end

data/lib/prompt_objects/primitives/think.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Primitives
+    # Optional standard-library capability for visible reasoning notes.
+    # Prompt Objects must declare this tool explicitly when its trace is useful.
+    class Think < Primitive
+      execution_policy parallel_safe: true, side_effect: :read
+
+      def name
+        "think"
+      end
+
+      def description
+        "Record a visible reasoning note before acting. Use only when an explicit thinking trace helps the human follow the work."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            thought: {
+              type: "string",
+              description: "Reasoning to show in the conversation"
+            }
+          },
+          required: ["thought"]
+        }
+      end
+
+      def receive(message, context:)
+        "Thought recorded."
+      end
+    end
+  end
+end

data/lib/prompt_objects/primitives/write_file.rb

@@ -4,6 +4,15 @@ module PromptObjects
   module Primitives
     # Primitive capability to write content to a file.
     class WriteFile < Primitive
+      execution_policy(
+        parallel_safe: true,
+        side_effect: :write,
+        resource_keys: ->(arguments, _context, _capability) {
+          path = arguments[:path] || arguments["path"]
+          path ? ["file:#{File.expand_path(path)}"] : []
+        }
+      )
+
       def name
         "write_file"
       end