Module: PromptObjects::Execution::Contracts

Defined in:
lib/prompt_objects/execution/contracts.rb

Overview

Stable names shared by the runtime protocol, persistence layer, and UI. The protocol fixtures in protocol/v1/fixtures are the wire-format examples.

Constant Summary collapse

PROTOCOL_VERSION = 
1
THREAD_TYPES = 
%w[human autonomous artifact delegation service api].freeze
RUN_STATUSES = 
%w[queued running waiting completed failed cancelled skipped interrupted].freeze
TOOL_EXECUTION_STATUSES = 
%w[pending running completed failed cancelled timed_out].freeze
RUN_EVENT_KINDS = 
%w[
  run_queued run_started model_started stream_delta model_completed
  tool_batch_started tool_started tool_completed tool_failed tool_cancelled
  delegation_started delegation_completed artifact_upserted env_data_changed
  run_waiting run_completed run_failed run_cancelled run_skipped run_interrupted
].freeze
SNAPSHOT_TYPES = 
%w[workspace_snapshot thread_snapshot artifact_snapshot].freeze
MUTATION_TYPES = 
%w[artifact_upserted artifact_removed env_data_changed].freeze
ENVELOPE_TYPES = 
(SNAPSHOT_TYPES + MUTATION_TYPES + ["run_event"]).freeze

Class Method Summary collapse

Class Method Details

.stringify_keys(value) ⇒ Object 



51
52
53
54
55
56
 
# File 'lib/prompt_objects/execution/contracts.rb', line 51

def stringify_keys(value)
  return value.transform_keys(&:to_s).transform_values { |item| stringify_keys(item) } if value.is_a?(Hash)
  return value.map { |item| stringify_keys(item) } if value.is_a?(Array)

  value
end

.validate_envelope!(envelope) ⇒ Object

Raises:

  • (ArgumentError) 


26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/prompt_objects/execution/contracts.rb', line 26

def validate_envelope!(envelope)
  data = stringify_keys(envelope)
  version = data.fetch("version")
  type = data.fetch("type")
  payload = data.fetch("payload")

  raise ArgumentError, "unsupported protocol version: #{version}" unless version == PROTOCOL_VERSION
  raise ArgumentError, "unknown protocol message type: #{type}" unless ENVELOPE_TYPES.include?(type)
  raise ArgumentError, "payload must be an object" unless payload.is_a?(Hash)

  validate_run_event!(payload) if type == "run_event"
  true
end

.validate_run_event!(payload) ⇒ Object

Raises:

  • (ArgumentError) 


40
41
42
43
44
45
46
47
48
49
 
# File 'lib/prompt_objects/execution/contracts.rb', line 40

def validate_run_event!(payload)
  %w[workspace_session_id thread_id run_id sequence workspace_cursor kind timestamp data].each do |key|
    payload.fetch(key)
  end

  kind = payload.fetch("kind")
  raise ArgumentError, "unknown run event kind: #{kind}" unless RUN_EVENT_KINDS.include?(kind)
  raise ArgumentError, "run event sequence must be positive" unless payload.fetch("sequence").to_i.positive?
  raise ArgumentError, "workspace cursor must be positive" unless payload.fetch("workspace_cursor").to_i.positive?
end