Class: Phronomy::InvocationContext

Inherits:
Object
  • Object
show all
Defined in:
lib/phronomy/invocation_context.rb

Overview

Carries all per-invocation context values through the call stack.

+InvocationContext+ is a plain value object (struct-like, frozen on creation) that replaces ad-hoc +Thread.current[...]+ propagation. Pass it explicitly wherever context needs to cross a method boundary or be handed to a child Task / TaskGroup.

Examples:

Build a context for a new agent invocation

ctx = Phronomy::InvocationContext.new(
  thread_id:         "conv-123",
  cancellation_token: Phronomy::CancellationToken.timeout_after(30),
  max_parallel_tools: 5
)
agent.invoke("Hello", invocation_context: ctx)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(thread_id: nil, session_id: nil, user_id: nil, cancellation_token: nil, deadline: nil, tracer_span: nil, token_budget: nil, max_parallel_tools: 10, approval_policy: nil, redaction_policy: nil, provider_limits: nil, task_id: nil, parent_task_id: nil) ⇒ InvocationContext

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of InvocationContext.

Parameters:

  • thread_id (String, nil) (defaults to: nil)
  • session_id (String, nil) (defaults to: nil)
  • user_id (String, nil) (defaults to: nil)
  • cancellation_token (CancellationToken, nil) (defaults to: nil)
  • deadline (Deadline, nil) (defaults to: nil)
  • tracer_span (Object, nil) (defaults to: nil)
  • token_budget (Integer, nil) (defaults to: nil)
  • max_parallel_tools (Integer) (defaults to: 10)
  • approval_policy (Object, nil) (defaults to: nil)
  • redaction_policy (Object, nil) (defaults to: nil)
  • provider_limits (Hash, nil) (defaults to: nil)
  • task_id (String, nil) (defaults to: nil)
  • parent_task_id (String, nil) (defaults to: nil) 


72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/phronomy/invocation_context.rb', line 72

def initialize(
  thread_id: nil,
  session_id: nil,
  user_id: nil,
  cancellation_token: nil,
  deadline: nil,
  tracer_span: nil,
  token_budget: nil,
  max_parallel_tools: 10,
  approval_policy: nil,
  redaction_policy: nil,
  provider_limits: nil,
  task_id: nil,
  parent_task_id: nil
)
  @thread_id = thread_id
  @session_id = session_id
  @user_id = user_id
  @cancellation_token = cancellation_token
  @deadline = deadline
  @tracer_span = tracer_span
  @token_budget = token_budget
  @max_parallel_tools = max_parallel_tools
  @approval_policy = approval_policy
  @redaction_policy = redaction_policy
  @provider_limits = provider_limits
  @task_id = task_id
  @parent_task_id = parent_task_id
end

Instance Attribute Details

#approval_policy ⇒ Object? (readonly)

Returns approval policy applied before write-scope tools.

Returns:

  • (Object, nil) —

    approval policy applied before write-scope tools



44
45
46
 
# File 'lib/phronomy/invocation_context.rb', line 44

def approval_policy
  @approval_policy
end

#cancellation_token ⇒ CancellationToken? (readonly)

Returns:



29
30
31
 
# File 'lib/phronomy/invocation_context.rb', line 29

def cancellation_token
  @cancellation_token
end

#deadline ⇒ Deadline? (readonly)

Returns:



32
33
34
 
# File 'lib/phronomy/invocation_context.rb', line 32

def deadline
  @deadline
end

#max_parallel_tools ⇒ Integer (readonly)

Returns maximum simultaneous tool calls (default: 10).

Returns:

  • (Integer) —

    maximum simultaneous tool calls (default: 10)



41
42
43
 
# File 'lib/phronomy/invocation_context.rb', line 41

def max_parallel_tools
  @max_parallel_tools
end

#parent_task_id ⇒ String? (readonly)

Returns task_id of the parent span / task.

Returns:

  • (String, nil) —

    task_id of the parent span / task



56
57
58
 
# File 'lib/phronomy/invocation_context.rb', line 56

def parent_task_id
  @parent_task_id
end

#provider_limits ⇒ Hash? (readonly)

Returns per-provider concurrency / rate-limit overrides.

Returns:

  • (Hash, nil) —

    per-provider concurrency / rate-limit overrides



50
51
52
 
# File 'lib/phronomy/invocation_context.rb', line 50

def provider_limits
  @provider_limits
end

#redaction_policy ⇒ Object? (readonly)

Returns redaction policy applied to tool args / results.

Returns:

  • (Object, nil) —

    redaction policy applied to tool args / results



47
48
49
 
# File 'lib/phronomy/invocation_context.rb', line 47

def redaction_policy
  @redaction_policy
end

#session_id ⇒ String? (readonly)

Returns session identifier (e.g. Rails session id).

Returns:

  • (String, nil) —

    session identifier (e.g. Rails session id)



23
24
25
 
# File 'lib/phronomy/invocation_context.rb', line 23

def session_id
  @session_id
end

#task_id ⇒ String? (readonly)

Returns unique identifier for this task in the trace tree.

Returns:

  • (String, nil) —

    unique identifier for this task in the trace tree



53
54
55
 
# File 'lib/phronomy/invocation_context.rb', line 53

def task_id
  @task_id
end

#thread_id ⇒ String? (readonly)

Returns conversation / workflow thread identifier.

Returns:

  • (String, nil) —

    conversation / workflow thread identifier



20
21
22
 
# File 'lib/phronomy/invocation_context.rb', line 20

def thread_id
  @thread_id
end

#token_budget ⇒ Integer? (readonly)

Returns max tokens the agent may consume this invocation.

Returns:

  • (Integer, nil) —

    max tokens the agent may consume this invocation



38
39
40
 
# File 'lib/phronomy/invocation_context.rb', line 38

def token_budget
  @token_budget
end

#tracer_span ⇒ Object? (readonly)

Returns OpenTelemetry / tracing span.

Returns:

  • (Object, nil) —

    OpenTelemetry / tracing span



35
36
37
 
# File 'lib/phronomy/invocation_context.rb', line 35

def tracer_span
  @tracer_span
end

#user_id ⇒ String? (readonly)

Returns end-user identifier for tracing / audit.

Returns:

  • (String, nil) —

    end-user identifier for tracing / audit



26
27
28
 
# File 'lib/phronomy/invocation_context.rb', line 26

def user_id
  @user_id
end

Instance Method Details

#effective_cancellation_token ⇒ CancellationToken

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Convenience: returns the cancellation token or a new never-cancelled token.

Returns:



129
130
131
 
# File 'lib/phronomy/invocation_context.rb', line 129

def effective_cancellation_token
  @cancellation_token || CancellationToken.new
end

#effective_timeout_token ⇒ CancellationToken?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the cancellation token to use for an invocation, taking both the explicit +cancellation_token+ and the +deadline+ into account.

  • When +cancellation_token+ is set, it is returned unchanged.
  • When only +deadline+ is set, a new CancellationToken is created and the deadline is attached to it via Deadline#attach_to.
  • When neither is set, returns +nil+.

Returns:



143
144
145
146
147
148
149
150
 
# File 'lib/phronomy/invocation_context.rb', line 143

def effective_timeout_token
  return @cancellation_token if @cancellation_token
  return nil if @deadline.nil?

  token = CancellationToken.new
  @deadline.attach_to(token)
  token
end

#merge(**overrides) ⇒ InvocationContext

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new +InvocationContext+ with the given attributes merged in. All other attributes are carried over unchanged.

Parameters:

  • overrides (Hash) —

    keyword arguments to override

Returns:



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/phronomy/invocation_context.rb', line 108

def merge(**overrides)
  InvocationContext.new(
    thread_id: overrides.fetch(:thread_id, @thread_id),
    session_id: overrides.fetch(:session_id, @session_id),
    user_id: overrides.fetch(:user_id, @user_id),
    cancellation_token: overrides.fetch(:cancellation_token, @cancellation_token),
    deadline: overrides.fetch(:deadline, @deadline),
    tracer_span: overrides.fetch(:tracer_span, @tracer_span),
    token_budget: overrides.fetch(:token_budget, @token_budget),
    max_parallel_tools: overrides.fetch(:max_parallel_tools, @max_parallel_tools),
    approval_policy: overrides.fetch(:approval_policy, @approval_policy),
    redaction_policy: overrides.fetch(:redaction_policy, @redaction_policy),
    provider_limits: overrides.fetch(:provider_limits, @provider_limits),
    task_id: overrides.fetch(:task_id, @task_id),
    parent_task_id: overrides.fetch(:parent_task_id, @parent_task_id)
  )
end