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::Concurrency::CancellationToken.timeout_after(30)
)
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, approval_policy: nil, redaction_policy: 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)
  • approval_policy (#call, nil) (defaults to: nil) —

    invocation-specific Tool approval policy

  • redaction_policy (Object, nil) (defaults to: nil)
  • task_id (String, nil) (defaults to: nil)
  • parent_task_id (String, nil) (defaults to: nil) 


64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/phronomy/invocation_context.rb', line 64

def initialize(
  thread_id: nil,
  session_id: nil,
  user_id: nil,
  cancellation_token: nil,
  deadline: nil,
  tracer_span: nil,
  token_budget: nil,
  approval_policy: nil,
  redaction_policy: 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
  @approval_policy = approval_policy
  @redaction_policy = redaction_policy
  @task_id = task_id
  @parent_task_id = parent_task_id
end

Instance Attribute Details

#approval_policy ⇒ #call? (readonly)

Returns invocation-specific Tool approval policy. The callable receives Phronomy::Agent::ApprovalEvaluationRequest.

Returns:

  • (#call, nil) —

    invocation-specific Tool approval policy. The callable receives Phronomy::Agent::ApprovalEvaluationRequest.



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

def approval_policy
  @approval_policy
end

#cancellation_token ⇒ CancellationToken? (readonly)

Returns:

  • (CancellationToken, nil) 


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

def cancellation_token
  @cancellation_token
end

#deadline ⇒ Deadline? (readonly)

Returns:

  • (Deadline, nil) 


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

def deadline
  @deadline
end

#parent_task_id ⇒ String? (readonly)

Returns task_id of the parent span / task.

Returns:

  • (String, nil) —

    task_id of the parent span / task



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

def parent_task_id
  @parent_task_id
end

#redaction_policy ⇒ Object? (readonly)

Returns redaction policy applied to tool args / results.

Returns:

  • (Object, nil) —

    redaction policy applied to tool args / results



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

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)



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

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



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

def task_id
  @task_id
end

#thread_id ⇒ String? (readonly)

Returns conversation / workflow thread identifier.

Returns:

  • (String, nil) —

    conversation / workflow thread identifier



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

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



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

def token_budget
  @token_budget
end

#tracer_span ⇒ Object? (readonly)

Returns OpenTelemetry / tracing span.

Returns:

  • (Object, nil) —

    OpenTelemetry / tracing span



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

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



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

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:

  • (CancellationToken) 


115
116
117
 
# File 'lib/phronomy/invocation_context.rb', line 115

def effective_cancellation_token
  @cancellation_token || Phronomy::Concurrency::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:

  • (CancellationToken, nil) 


129
130
131
132
133
134
135
136
 
# File 'lib/phronomy/invocation_context.rb', line 129

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

  token = Phronomy::Concurrency::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:



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/phronomy/invocation_context.rb', line 96

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),
    approval_policy: overrides.fetch(:approval_policy, @approval_policy),
    redaction_policy: overrides.fetch(:redaction_policy, @redaction_policy),
    task_id: overrides.fetch(:task_id, @task_id),
    parent_task_id: overrides.fetch(:parent_task_id, @parent_task_id)
  )
end