Class: Spurline::Orchestration::TaskEnvelope

Inherits:
Object
  • Object
show all
Defined in:
lib/spurline/orchestration/task_envelope.rb

Overview

Immutable work unit for worker execution.

Constant Summary collapse

CURRENT_VERSION = 
"1.0"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(instruction:, acceptance_criteria:, task_id: SecureRandom.uuid, version: CURRENT_VERSION, input_files: [], constraints: {}, output_spec: {}, scoped_context: nil, parent_session_id: nil, max_turns: 10, max_tool_calls: 20, metadata: {}) ⇒ TaskEnvelope

Returns a new instance of TaskEnvelope.

Parameters:

  • instruction (String) —

    Natural language task description (required)

  • acceptance_criteria (Array<String>) —

    What the output must contain (required)

  • task_id (String) (defaults to: SecureRandom.uuid) —

    UUID (auto-generated)

  • version (String) (defaults to: CURRENT_VERSION) —

    Schema version

  • input_files (Array<Hash>) (defaults to: []) —

    Files the worker needs { path:, content: }

  • constraints (Hash) (defaults to: {}) —

    Behavioral limits { no_modify: […], read_only: true, … }

  • output_spec (Hash) (defaults to: {}) —

    Expected output format { type: :patch|:file|:answer, … }

  • scoped_context (Object, nil) (defaults to: nil) —

    Optional execution scope (M2.3)

  • parent_session_id (String, nil) (defaults to: nil) —

    For audit correlation

  • max_turns (Integer) (defaults to: 10) —

    Safety limit (default 10)

  • max_tool_calls (Integer) (defaults to: 20) —

    Safety limit (default 20)

  • metadata (Hash) (defaults to: {}) —

    Arbitrary extra data



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 28

def initialize(
  instruction:,
  acceptance_criteria:,
  task_id: SecureRandom.uuid,
  version: CURRENT_VERSION,
  input_files: [],
  constraints: {},
  output_spec: {},
  scoped_context: nil,
  parent_session_id: nil,
  max_turns: 10,
  max_tool_calls: 20,
  metadata: {}
)
  validate_instruction!(instruction)
  validate_acceptance_criteria!(acceptance_criteria)
  validate_limit!(max_turns, name: "max_turns")
  validate_limit!(max_tool_calls, name: "max_tool_calls")

  @task_id = task_id.to_s
  @version = version.to_s
  @instruction = instruction.to_s
  @input_files = deep_copy(input_files || [])
  @constraints = deep_copy(constraints || {})
  @acceptance_criteria = acceptance_criteria.map(&:to_s)
  @output_spec = deep_copy(output_spec || {})
  @scoped_context = normalize_scoped_context(scoped_context)
  @parent_session_id = parent_session_id&.to_s
  @max_turns = max_turns
  @max_tool_calls = max_tool_calls
  @metadata = deep_copy(metadata || {})

  deep_freeze(@input_files)
  deep_freeze(@constraints)
  deep_freeze(@acceptance_criteria)
  deep_freeze(@output_spec)
  deep_freeze(@metadata)
  if @scoped_context.is_a?(Hash) || @scoped_context.is_a?(Array)
    deep_freeze(@scoped_context)
  elsif @scoped_context.respond_to?(:freeze)
    @scoped_context.freeze
  end
  freeze
end

Instance Attribute Details

#acceptance_criteria ⇒ Object (readonly)

Returns the value of attribute acceptance_criteria.



11
12
13
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 11

def acceptance_criteria
  @acceptance_criteria
end

#constraints ⇒ Object (readonly)

Returns the value of attribute constraints.



11
12
13
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 11

def constraints
  @constraints
end

#input_files ⇒ Object (readonly)

Returns the value of attribute input_files.



11
12
13
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 11

def input_files
  @input_files
end

#instruction ⇒ Object (readonly)

Returns the value of attribute instruction.



11
12
13
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 11

def instruction
  @instruction
end

#max_tool_calls ⇒ Object (readonly)

Returns the value of attribute max_tool_calls.



11
12
13
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 11

def max_tool_calls
  @max_tool_calls
end

#max_turns ⇒ Object (readonly)

Returns the value of attribute max_turns.



11
12
13
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 11

def max_turns
  @max_turns
end

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata.



11
12
13
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 11

def metadata
  @metadata
end

#output_spec ⇒ Object (readonly)

Returns the value of attribute output_spec.



11
12
13
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 11

def output_spec
  @output_spec
end

#parent_session_id ⇒ Object (readonly)

Returns the value of attribute parent_session_id.



11
12
13
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 11

def parent_session_id
  @parent_session_id
end

#scoped_context ⇒ Object (readonly)

Returns the value of attribute scoped_context.



11
12
13
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 11

def scoped_context
  @scoped_context
end

#task_id ⇒ Object (readonly)

Returns the value of attribute task_id.



11
12
13
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 11

def task_id
  @task_id
end

#version ⇒ Object (readonly)

Returns the value of attribute version.



11
12
13
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 11

def version
  @version
end

Class Method Details

.from_h(data) ⇒ Object 



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 90

def self.from_h(data)
  hash = deep_symbolize(data || {})
  new(
    task_id: hash[:task_id] || SecureRandom.uuid,
    version: hash[:version] || CURRENT_VERSION,
    instruction: hash.fetch(:instruction),
    input_files: hash[:input_files] || [],
    constraints: hash[:constraints] || {},
    acceptance_criteria: hash.fetch(:acceptance_criteria),
    output_spec: hash[:output_spec] || {},
    scoped_context: hash[:scoped_context],
    parent_session_id: hash[:parent_session_id],
    max_turns: hash[:max_turns] || 10,
    max_tool_calls: hash[:max_tool_calls] || 20,
    metadata: hash[:metadata] || {}
  )
end

Instance Method Details

#to_h ⇒ Object 



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/spurline/orchestration/task_envelope.rb', line 73

def to_h
  {
    task_id: task_id,
    version: version,
    instruction: instruction,
    input_files: deep_copy(input_files),
    constraints: deep_copy(constraints),
    acceptance_criteria: deep_copy(acceptance_criteria),
    output_spec: deep_copy(output_spec),
    scoped_context: serialize_scoped_context(scoped_context),
    parent_session_id: parent_session_id,
    max_turns: max_turns,
    max_tool_calls: max_tool_calls,
    metadata: deep_copy(metadata),
  }
end