blib/lib/SignalWire/Contexts.pm

filter: Statementstmt 86.5% 445 / 514 Branchbran 69.5% 146 / 210 Conditioncond 62.5% 15 / 24 MC/DCmcdc 42.8% 6 / 14 Subroutinesub 86.3% 95 / 110 Podpod 0.0% 0 / 52 totaltotal 76.5% 707 / 924 CC 132 SCAR 27.7
CC
132
Cov
81%
validate
69.6
add_enter_filler
20.0
to_hash
15.0
CRAP 15.9
« blib/lib/SignalWire/Utils/UrlValidator.pm ↑ Summary scripts/enumerate_surface.pl »
1 package SignalWire::Contexts;
2 19 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 19 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 19 ▶use JSON ();
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 19 our $MAX_CONTEXTS = 50;
7 19 our $MAX_STEPS_PER_CONTEXT = 100;
8  
9 # Reserved tool names auto-injected by the runtime when contexts/steps are
10 # present. User-defined SWAIG tools must not collide with these names:
11 # - next_step / change_context are injected when valid_steps or
12 # valid_contexts is set so the model can navigate the flow.
13 # - gather_submit is injected while a step's gather_info is collecting
14 # answers.
15 # ContextBuilder->validate rejects any agent that registers a user tool
16 # sharing one of these names (see the validation in
17 # SignalWire::Contexts::ContextBuilder::validate below).
18 19 our %RESERVED_NATIVE_TOOL_NAMES = (
19 next_step => 1,
20 change_context => 1,
21 gather_submit => 1,
22 );
23  
24 # ==========================================================================
25 # GatherQuestion
26 # ==========================================================================
27 package SignalWire::Contexts::GatherQuestion;
28 19 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
29 19 ▶use JSON ();
Subroutine BEGIN: called CC=1 SCAR=0.0
30  
31 19 has 'key' => (is => 'ro', required => 1);
32 19 has 'question' => (is => 'ro', required => 1);
33 0 ▶has 'type' => (is => 'ro', default => sub { 'string' });
Subroutine __ANON__: not called CC=1 SCAR=1.2
34 0 ▶has 'confirm' => (is => 'ro', default => sub { 0 });
Subroutine __ANON__: not called CC=1 SCAR=1.2
35 0 ▶has 'prompt' => (is => 'ro', default => sub { undef });
Subroutine __ANON__: not called CC=1 SCAR=1.2
36 0 ▶has 'functions' => (is => 'ro', default => sub { undef });
Subroutine __ANON__: not called CC=1 SCAR=1.2
37  
38 2 ▶sub to_hash {
Subroutine to_hash: called CC=5 SCAR=16.5
Pod undocumented
39 2 my ($self) = @_;
40 2 my %d = (key => $self->key, question => $self->question);
41 2 ▶ $d{type} = $self->type if $self->type ne 'string';
Branch: 1 branch
BranchTrueFalseTotal
if $self->type ne "string" 0 2 2
42 2 ▶ $d{confirm} = JSON::true if $self->confirm;
Branch: 1 branch
BranchTrueFalseTotal
if $self->confirm 1 1 2
43 2 ▶ $d{prompt} = $self->prompt if defined $self->prompt;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->prompt 0 2 2
44 2 ▶ $d{functions} = $self->functions if defined $self->functions;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->functions 0 2 2
45 2 return \%d;
46 }
47  
48 # ==========================================================================
49 # GatherInfo
50 # ==========================================================================
51 package SignalWire::Contexts::GatherInfo;
52 19 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
53  
54 4 ▶has '_questions' => (is => 'rw', default => sub { [] });
Subroutine __ANON__: called CC=1 SCAR=0.0
55 0 ▶has '_output_key' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: not called CC=1 SCAR=1.2
56 0 ▶has '_completion_action' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: not called CC=1 SCAR=1.2
57 0 ▶has '_prompt' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: not called CC=1 SCAR=1.2
58  
59 5 ▶sub add_question {
Subroutine add_question: called CC=3 SCAR=11.0
Pod undocumented
60 5 my ($self, %opts) = @_;
61 my $q = SignalWire::Contexts::GatherQuestion->new(
62 key => $opts{key},
63 question => $opts{question},
64 type => $opts{type} // 'string',
65 confirm => $opts{confirm} // 0,
66 prompt => $opts{prompt},
67 functions => $opts{functions},
68 5 ▶ );
Condition100%4/4
$opts{"type"} // "string"
l!l
14
$opts{"confirm"} // 0
l!l
14
MC/DC100%1/1
$opts{"type"} // "string"
$opts{"type"}
MC/DC100%1/1
$opts{"confirm"} // 0
$opts{"confirm"}
Truth table100%2/2
A
A= $opts{"type"}
Aresult
11
00
Truth table100%2/2
A
A= $opts{"confirm"}
Aresult
11
00
69 5 push @{ $self->_questions }, $q;
70 5 return $self;
71 }
72  
73 1 ▶sub to_hash {
Subroutine to_hash: called CC=5 SCAR=16.6
Pod undocumented
74 1 my ($self) = @_;
75 1 ▶ die "gather_info must have at least one question" unless @{ $self->_questions };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->_questions;} 0 1 1
76 1 my %d = (questions => [ map { $_->to_hash } @{ $self->_questions } ]);
77 1 ▶ $d{prompt} = $self->_prompt if defined $self->_prompt;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_prompt 1 0 1
78 1 ▶ $d{output_key} = $self->_output_key if defined $self->_output_key;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_output_key 1 0 1
79 1 ▶ $d{completion_action} = $self->_completion_action if defined $self->_completion_action;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_completion_action 1 0 1
80 1 return \%d;
81 }
82  
83 # ==========================================================================
84 # Step
85 # ==========================================================================
86 package SignalWire::Contexts::Step;
87 19 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
88 19 ▶use JSON ();
Subroutine BEGIN: called CC=1 SCAR=0.0
89  
90 19 has 'name' => (is => 'ro', required => 1);
91  
92 41 ▶has '_text' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
93 41 ▶has '_step_criteria' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
94 41 ▶has '_functions' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
95 41 ▶has '_valid_steps' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
96 41 ▶has '_valid_contexts' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
97 41 ▶has '_sections' => (is => 'rw', default => sub { [] });
Subroutine __ANON__: called CC=1 SCAR=0.0
98 41 ▶has '_gather_info' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
99 41 ▶has '_end' => (is => 'rw', default => sub { 0 });
Subroutine __ANON__: called CC=1 SCAR=0.0
100 41 ▶has '_skip_user_turn' => (is => 'rw', default => sub { 0 });
Subroutine __ANON__: called CC=1 SCAR=0.0
101 41 ▶has '_skip_to_next_step' => (is => 'rw', default => sub { 0 });
Subroutine __ANON__: called CC=1 SCAR=0.0
102 41 ▶has '_reset_system_prompt' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
103 41 ▶has '_reset_user_prompt' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
104 41 ▶has '_reset_consolidate' => (is => 'rw', default => sub { 0 });
Subroutine __ANON__: called CC=1 SCAR=0.0
105 41 ▶has '_reset_full_reset' => (is => 'rw', default => sub { 0 });
Subroutine __ANON__: called CC=1 SCAR=0.0
106  
107 36 ▶sub set_text {
Subroutine set_text: called CC=2 SCAR=6.9
Pod undocumented
108 36 my ($self, $text) = @_;
109 die "Cannot use set_text() when POM sections have been added"
110 36 ▶ if @{ $self->_sections };
Branch: 1 branch
BranchTrueFalseTotal
if @{$self->_sections;} 1 35 36
111 35 $self->_text($text);
112 35 return $self;
113 }
114  
115 7 ▶sub add_section {
Subroutine add_section: called CC=2 SCAR=6.9
Pod undocumented
116 7 my ($self, $title, $body) = @_;
117 7 ▶ die "Cannot add POM sections when set_text() has been used"
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_text 1 6 7
118 if defined $self->_text;
119 6 push @{ $self->_sections }, { title => $title, body => $body };
120 6 return $self;
121 }
122  
123 2 ▶sub add_bullets {
Subroutine add_bullets: called CC=2 SCAR=7.0
Pod undocumented
124 2 my ($self, $title, $bullets) = @_;
125 2 ▶ die "Cannot add POM sections when set_text() has been used"
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_text 0 2 2
126 if defined $self->_text;
127 2 push @{ $self->_sections }, { title => $title, bullets => $bullets };
128 2 return $self;
129 }
130  
131 2 ▶sub set_step_criteria {
Subroutine set_step_criteria: called CC=1 SCAR=0.0
Pod undocumented
132 2 my ($self, $criteria) = @_;
133 2 $self->_step_criteria($criteria);
134 2 return $self;
135 }
136  
137 #
138 # set_functions — set which non-internal functions are callable while this
139 # step is active.
140 #
141 # IMPORTANT — inheritance behavior:
142 # If you do NOT call this method, the step inherits whichever function
143 # set was active on the previous step (or the previous context's last
144 # step). The server-side runtime only resets the active set when a step
145 # explicitly declares its `functions` field. This is the most common
146 # source of bugs in multi-step agents: forgetting set_functions on a
147 # later step lets the previous step's tools leak through. Best practice
148 # is to call set_functions explicitly on every step that should differ
149 # from the previous one.
150 #
151 # Keep the per-step active set small: LLM tool selection accuracy
152 # degrades noticeably past ~7-8 simultaneously-active tools per call.
153 # Use per-step whitelisting to partition large tool collections.
154 #
155 # Arguments:
156 # $functions — one of:
157 # - arrayref of function names (whitelist)
158 # - empty arrayref [] (explicit disable-all)
159 # - the string "none" (synonym for [])
160 #
161 # Internal functions (e.g. gather_submit, hangup_hook) are ALWAYS protected
162 # and cannot be deactivated by this whitelist. The native navigation tools
163 # next_step and change_context are injected automatically when
164 # set_valid_steps / set_valid_contexts is used; they are not affected by
165 # this list and do not need to appear in it.
166 #
167 3 ▶sub set_functions {
Subroutine set_functions: called CC=1 SCAR=0.0
Pod undocumented
168 3 my ($self, $functions) = @_;
169 3 $self->_functions($functions);
170 3 return $self;
171 }
172  
173 4 ▶sub set_valid_steps {
Subroutine set_valid_steps: called CC=1 SCAR=0.0
Pod undocumented
174 4 my ($self, $steps) = @_;
175 4 $self->_valid_steps($steps);
176 4 return $self;
177 }
178  
179 1 ▶sub set_valid_contexts {
Subroutine set_valid_contexts: called CC=1 SCAR=0.0
Pod undocumented
180 1 my ($self, $contexts) = @_;
181 1 $self->_valid_contexts($contexts);
182 1 return $self;
183 }
184  
185 #
186 # set_end — mark this step as terminal for the step flow.
187 #
188 # IMPORTANT: end=1 does NOT end the conversation or hang up the call.
189 # It exits step mode entirely after this step executes — clearing the
190 # steps list, current step index, valid_steps, and valid_contexts. The
191 # agent keeps running, but operates only under the base system prompt
192 # and the context-level prompt; no more step instructions are injected
193 # and no more next_step tool is offered.
194 #
195 # To actually end the call, call a hangup tool or define a hangup hook.
196 #
197 1 ▶sub set_end {
Subroutine set_end: called CC=2 SCAR=7.1
Pod undocumented
198 1 my ($self, $end) = @_;
199 1 ▶ $self->_end($end ? 1 : 0);
Branch: 1 branch
BranchTrueFalseTotal
$end ? : 1 0 1
200 1 return $self;
201 }
202  
203 1 ▶sub set_skip_user_turn {
Subroutine set_skip_user_turn: called CC=2 SCAR=7.1
Pod undocumented
204 1 my ($self, $skip) = @_;
205 1 ▶ $self->_skip_user_turn($skip ? 1 : 0);
Branch: 1 branch
BranchTrueFalseTotal
$skip ? : 1 0 1
206 1 return $self;
207 }
208  
209 1 ▶sub set_skip_to_next_step {
Subroutine set_skip_to_next_step: called CC=2 SCAR=7.1
Pod undocumented
210 1 my ($self, $skip) = @_;
211 1 ▶ $self->_skip_to_next_step($skip ? 1 : 0);
Branch: 1 branch
BranchTrueFalseTotal
$skip ? : 1 0 1
212 1 return $self;
213 }
214  
215 4 ▶sub set_gather_info {
Subroutine set_gather_info: called CC=1 SCAR=0.0
Pod undocumented
216 4 my ($self, %opts) = @_;
217 $self->_gather_info(SignalWire::Contexts::GatherInfo->new(
218 _output_key => $opts{output_key},
219 _completion_action => $opts{completion_action},
220 _prompt => $opts{prompt},
221 4 ));
222 4 return $self;
223 }
224  
225 #
226 # add_gather_question — add a question to this step's gather_info.
227 # set_gather_info() must be called before this method.
228 #
229 # IMPORTANT — gather mode locks function access:
230 # While the model is asking gather questions, the runtime forcibly
231 # deactivates ALL of the step's other functions. The only callable
232 # tools during a gather question are:
233 #
234 # - gather_submit (the native answer-submission tool)
235 # - Whatever names you pass in this question's `functions` option
236 #
237 # next_step and change_context are also filtered out — the model
238 # cannot navigate away until the gather completes. This is by design:
239 # it forces a tight ask → submit → next-question loop.
240 #
241 # If a question needs to call out to a tool (e.g. validate an email,
242 # geocode a ZIP), list that tool name in this question's `functions`
243 # option. Functions listed here are active ONLY for this question.
244 #
245 6 ▶sub add_gather_question {
Subroutine add_gather_question: called CC=2 SCAR=6.9
Pod undocumented
246 6 my ($self, %opts) = @_;
247 6 ▶ die "Must call set_gather_info() before add_gather_question()"
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->_gather_info 1 5 6
248 unless defined $self->_gather_info;
249 5 $self->_gather_info->add_question(%opts);
250 5 return $self;
251 }
252  
253 1 ▶sub clear_sections {
Subroutine clear_sections: called CC=1 SCAR=0.0
Pod undocumented
254 1 my ($self) = @_;
255 1 $self->_sections([]);
256 1 $self->_text(undef);
257 1 return $self;
258 }
259  
260 1 ▶sub set_reset_system_prompt {
Subroutine set_reset_system_prompt: called CC=1 SCAR=0.0
Pod undocumented
261 1 my ($self, $sp) = @_;
262 1 $self->_reset_system_prompt($sp);
263 1 return $self;
264 }
265  
266 1 ▶sub set_reset_user_prompt {
Subroutine set_reset_user_prompt: called CC=1 SCAR=0.0
Pod undocumented
267 1 my ($self, $up) = @_;
268 1 $self->_reset_user_prompt($up);
269 1 return $self;
270 }
271  
272 1 ▶sub set_reset_consolidate {
Subroutine set_reset_consolidate: called CC=2 SCAR=7.1
Pod undocumented
273 1 my ($self, $c) = @_;
274 1 ▶ $self->_reset_consolidate($c ? 1 : 0);
Branch: 1 branch
BranchTrueFalseTotal
$c ? : 1 0 1
275 1 return $self;
276 }
277  
278 1 ▶sub set_reset_full_reset {
Subroutine set_reset_full_reset: called CC=2 SCAR=7.1
Pod undocumented
279 1 my ($self, $fr) = @_;
280 1 ▶ $self->_reset_full_reset($fr ? 1 : 0);
Branch: 1 branch
BranchTrueFalseTotal
$fr ? : 1 0 1
281 1 return $self;
282 }
283  
284 27 ▶sub _render_text {
Subroutine _render_text: called CC=5 SCAR=16.1
285 27 my ($self) = @_;
286 27 ▶ return $self->_text if defined $self->_text;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_text 25 2 27
287  
288 die "Step '" . $self->name . "' has no text or POM sections defined"
289 2 ▶ unless @{ $self->_sections };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->_sections;} 0 2 2
290  
291 2 my @parts;
292 2 for my $sec (@{ $self->_sections }) {
293 4 ▶ if (exists $sec->{bullets}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $sec->{'bullets'}) { } 2 2 4
294 2 push @parts, "## $sec->{title}";
295 2 push @parts, map { "- $_" } @{ $sec->{bullets} };
296 } else {
297 2 push @parts, "## $sec->{title}";
298 2 push @parts, $sec->{body};
299 }
300 4 push @parts, '';
301 }
302 2 my $text = join("\n", @parts);
303 2 $text =~ s/\s+$//;
304 2 return $text;
305 }
306  
307 27 ▶sub to_hash {
Subroutine to_hash: called CC=14 SCAR=26.4
Pod undocumented
308 27 my ($self) = @_;
309 27 my %d = (
310 name => $self->name,
311 text => $self->_render_text,
312 );
313  
314 27 ▶ $d{step_criteria} = $self->_step_criteria if defined $self->_step_criteria;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_step_criteria 2 25 27
315 27 ▶ $d{functions} = $self->_functions if defined $self->_functions;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_functions 3 24 27
316 27 ▶ $d{valid_steps} = $self->_valid_steps if defined $self->_valid_steps;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_valid_steps 3 24 27
317 27 ▶ $d{valid_contexts} = $self->_valid_contexts if defined $self->_valid_contexts;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_valid_contexts 1 26 27
318 27 ▶ $d{end} = JSON::true if $self->_end;
Branch: 1 branch
BranchTrueFalseTotal
if $self->_end 1 26 27
319 27 ▶ $d{skip_user_turn} = JSON::true if $self->_skip_user_turn;
Branch: 1 branch
BranchTrueFalseTotal
if $self->_skip_user_turn 1 26 27
320 27 ▶ $d{skip_to_next_step} = JSON::true if $self->_skip_to_next_step;
Branch: 1 branch
BranchTrueFalseTotal
if $self->_skip_to_next_step 1 26 27
321  
322 27 my %reset;
323 27 ▶ $reset{system_prompt} = $self->_reset_system_prompt if defined $self->_reset_system_prompt;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_reset_system_prompt 1 26 27
324 27 ▶ $reset{user_prompt} = $self->_reset_user_prompt if defined $self->_reset_user_prompt;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_reset_user_prompt 1 26 27
325 27 ▶ $reset{consolidate} = JSON::true if $self->_reset_consolidate;
Branch: 1 branch
BranchTrueFalseTotal
if $self->_reset_consolidate 1 26 27
326 27 ▶ $reset{full_reset} = JSON::true if $self->_reset_full_reset;
Branch: 1 branch
BranchTrueFalseTotal
if $self->_reset_full_reset 1 26 27
327 27 ▶ $d{reset} = \%reset if keys %reset;
Branch: 1 branch
BranchTrueFalseTotal
if keys %reset 1 26 27
328  
329 27 ▶ $d{gather_info} = $self->_gather_info->to_hash if defined $self->_gather_info;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_gather_info 1 26 27
330  
331 27 return \%d;
332 }
333  
334 # ==========================================================================
335 # Context
336 # ==========================================================================
337 package SignalWire::Contexts::Context;
338 19 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
339 19 ▶use JSON ();
Subroutine BEGIN: called CC=1 SCAR=0.0
340  
341 19 has 'name' => (is => 'ro', required => 1);
342  
343 31 ▶has '_steps' => (is => 'rw', default => sub { {} });
Subroutine __ANON__: called CC=1 SCAR=0.0
344 31 ▶has '_step_order' => (is => 'rw', default => sub { [] });
Subroutine __ANON__: called CC=1 SCAR=0.0
345 31 ▶has '_valid_contexts' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
346 31 ▶has '_valid_steps' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
347 31 ▶has '_initial_step' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
348 31 ▶has '_post_prompt' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
349 31 ▶has '_system_prompt' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
350 31 ▶has '_system_prompt_sections' => (is => 'rw', default => sub { [] });
Subroutine __ANON__: called CC=1 SCAR=0.0
351 31 ▶has '_consolidate' => (is => 'rw', default => sub { 0 });
Subroutine __ANON__: called CC=1 SCAR=0.0
352 31 ▶has '_full_reset' => (is => 'rw', default => sub { 0 });
Subroutine __ANON__: called CC=1 SCAR=0.0
353 31 ▶has '_user_prompt' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
354 31 ▶has '_isolated' => (is => 'rw', default => sub { 0 });
Subroutine __ANON__: called CC=1 SCAR=0.0
355 31 ▶has '_prompt_text' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
356 31 ▶has '_prompt_sections' => (is => 'rw', default => sub { [] });
Subroutine __ANON__: called CC=1 SCAR=0.0
357 31 ▶has '_enter_fillers' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
358 31 ▶has '_exit_fillers' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
359  
360 31 ▶sub add_step {
Subroutine add_step: called CC=8 SCAR=20.8
Pod undocumented
361 31 my ($self, $name, %opts) = @_;
362 die "Step '$name' already exists in context '" . $self->name . "'"
363 31 ▶ if exists $self->_steps->{$name};
Branch: 1 branch
BranchTrueFalseTotal
if exists $self->_steps->{$name} 1 30 31
364 die "Maximum steps per context ($SignalWire::Contexts::MAX_STEPS_PER_CONTEXT) exceeded"
365 30 ▶ if keys %{ $self->_steps } >= $SignalWire::Contexts::MAX_STEPS_PER_CONTEXT;
Branch: 1 branch
BranchTrueFalseTotal
if keys %{$self->_steps;} >= $SignalWire::Contexts::MAX_STEPS_PER_CONTEXT 0 30 30
366  
367 30 my $step = SignalWire::Contexts::Step->new(name => $name);
368 30 $self->_steps->{$name} = $step;
369 30 push @{ $self->_step_order }, $name;
370  
371 30 ▶ $step->add_section('Task', $opts{task}) if defined $opts{task};
Branch: 1 branch
BranchTrueFalseTotal
if defined $opts{"task"} 3 27 30
372 30 ▶ $step->add_bullets('Process', $opts{bullets}) if defined $opts{bullets};
Branch: 1 branch
BranchTrueFalseTotal
if defined $opts{"bullets"} 1 29 30
373 30 ▶ $step->set_step_criteria($opts{criteria}) if defined $opts{criteria};
Branch: 1 branch
BranchTrueFalseTotal
if defined $opts{"criteria"} 1 29 30
374 30 ▶ $step->set_functions($opts{functions}) if defined $opts{functions};
Branch: 1 branch
BranchTrueFalseTotal
if defined $opts{"functions"} 1 29 30
375 30 ▶ $step->set_valid_steps($opts{valid_steps}) if defined $opts{valid_steps};
Branch: 1 branch
BranchTrueFalseTotal
if defined $opts{"valid_steps"} 1 29 30
376  
377 30 return $step;
378 }
379  
380 4 ▶sub get_step {
Subroutine get_step: called CC=1 SCAR=0.0
Pod undocumented
381 4 my ($self, $name) = @_;
382 4 return $self->_steps->{$name};
383 }
384  
385 1 ▶sub remove_step {
Subroutine remove_step: called CC=2 SCAR=7.0
Pod undocumented
386 1 my ($self, $name) = @_;
387 1 ▶ if (exists $self->_steps->{$name}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $self->_steps->{$name}) 1 0 1
388 1 delete $self->_steps->{$name};
389 1 $self->_step_order([ grep { $_ ne $name } @{ $self->_step_order } ]);
390 }
391 1 return $self;
392 }
393  
394 1 ▶sub move_step {
Subroutine move_step: called CC=2 SCAR=7.0
Pod undocumented
395 1 my ($self, $name, $position) = @_;
396 die "Step '$name' not found in context '" . $self->name . "'"
397 1 ▶ unless exists $self->_steps->{$name};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->_steps->{$name} 0 1 1
398 1 my @order = grep { $_ ne $name } @{ $self->_step_order };
399 1 splice @order, $position, 0, $name;
400 1 $self->_step_order(\@order);
401 1 return $self;
402 }
403  
404 #
405 # set_initial_step — set which step the context starts on when entered.
406 #
407 # By default, a context starts on its first step (index 0). Use this
408 # to skip a preamble step on re-entry via change_context.
409 #
410 0 ▶sub set_initial_step {
Subroutine set_initial_step: not called CC=1 SCAR=6.9
Pod undocumented
411 0 my ($self, $step_name) = @_;
412 0 $self->_initial_step($step_name);
413 0 return $self;
414 }
415  
416 4 ▶sub set_valid_contexts {
Subroutine set_valid_contexts: called CC=1 SCAR=0.0
Pod undocumented
417 4 my ($self, $contexts) = @_;
418 4 $self->_valid_contexts($contexts);
419 4 return $self;
420 }
421  
422 1 ▶sub set_valid_steps {
Subroutine set_valid_steps: called CC=1 SCAR=0.0
Pod undocumented
423 1 my ($self, $steps) = @_;
424 1 $self->_valid_steps($steps);
425 1 return $self;
426 }
427  
428 1 ▶sub set_post_prompt {
Subroutine set_post_prompt: called CC=1 SCAR=0.0
Pod undocumented
429 1 my ($self, $pp) = @_;
430 1 $self->_post_prompt($pp);
431 1 return $self;
432 }
433  
434 1 ▶sub set_system_prompt {
Subroutine set_system_prompt: called CC=2 SCAR=7.0
Pod undocumented
435 1 my ($self, $sp) = @_;
436 die "Cannot use set_system_prompt() when POM sections have been added for system prompt"
437 1 ▶ if @{ $self->_system_prompt_sections };
Branch: 1 branch
BranchTrueFalseTotal
if @{$self->_system_prompt_sections;} 0 1 1
438 1 $self->_system_prompt($sp);
439 1 return $self;
440 }
441  
442 1 ▶sub set_consolidate {
Subroutine set_consolidate: called CC=2 SCAR=7.1
Pod undocumented
443 1 my ($self, $c) = @_;
444 1 ▶ $self->_consolidate($c ? 1 : 0);
Branch: 1 branch
BranchTrueFalseTotal
$c ? : 1 0 1
445 1 return $self;
446 }
447  
448 1 ▶sub set_full_reset {
Subroutine set_full_reset: called CC=2 SCAR=7.1
Pod undocumented
449 1 my ($self, $fr) = @_;
450 1 ▶ $self->_full_reset($fr ? 1 : 0);
Branch: 1 branch
BranchTrueFalseTotal
$fr ? : 1 0 1
451 1 return $self;
452 }
453  
454 1 ▶sub set_user_prompt {
Subroutine set_user_prompt: called CC=1 SCAR=0.0
Pod undocumented
455 1 my ($self, $up) = @_;
456 1 $self->_user_prompt($up);
457 1 return $self;
458 }
459  
460 #
461 # set_isolated — mark this context as isolated. Entering it wipes
462 # conversation history.
463 #
464 # When isolated=1 and the context is entered via change_context, the
465 # runtime wipes the conversation array. The model starts fresh with only
466 # the new context's system_prompt + step instructions, with no memory of
467 # prior turns.
468 #
469 # EXCEPTION — reset overrides the wipe:
470 # If the context also has a reset configuration (via set_consolidate
471 # or set_full_reset), the wipe is skipped in favor of the reset
472 # behavior. Use reset with consolidate=1 to summarize prior history
473 # into a single message instead of dropping it entirely.
474 #
475 # Use cases: switching to a sensitive billing flow that should not see
476 # prior small-talk; handing off to a different agent persona; resetting
477 # after a long off-topic detour.
478 #
479 1 ▶sub set_isolated {
Subroutine set_isolated: called CC=2 SCAR=7.1
Pod undocumented
480 1 my ($self, $iso) = @_;
481 1 ▶ $self->_isolated($iso ? 1 : 0);
Branch: 1 branch
BranchTrueFalseTotal
$iso ? : 1 0 1
482 1 return $self;
483 }
484  
485 0 ▶sub add_system_section {
Subroutine add_system_section: not called CC=2 SCAR=17.9
Pod undocumented
486 0 my ($self, $title, $body) = @_;
487 0 ▶ die "Cannot add POM sections for system prompt when set_system_prompt() has been used"
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_system_prompt 0 0 0
488 if defined $self->_system_prompt;
489 0 push @{ $self->_system_prompt_sections }, { title => $title, body => $body };
490 0 return $self;
491 }
492  
493 0 ▶sub add_system_bullets {
Subroutine add_system_bullets: not called CC=2 SCAR=17.9
Pod undocumented
494 0 my ($self, $title, $bullets) = @_;
495 0 ▶ die "Cannot add POM sections for system prompt when set_system_prompt() has been used"
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_system_prompt 0 0 0
496 if defined $self->_system_prompt;
497 0 push @{ $self->_system_prompt_sections }, { title => $title, bullets => $bullets };
498 0 return $self;
499 }
500  
501 1 ▶sub set_prompt {
Subroutine set_prompt: called CC=2 SCAR=7.0
Pod undocumented
502 1 my ($self, $prompt) = @_;
503 die "Cannot use set_prompt() when POM sections have been added"
504 1 ▶ if @{ $self->_prompt_sections };
Branch: 1 branch
BranchTrueFalseTotal
if @{$self->_prompt_sections;} 0 1 1
505 1 $self->_prompt_text($prompt);
506 1 return $self;
507 }
508  
509 1 ▶sub add_section {
Subroutine add_section: called CC=2 SCAR=7.0
Pod undocumented
510 1 my ($self, $title, $body) = @_;
511 1 ▶ die "Cannot add POM sections when set_prompt() has been used"
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_prompt_text 0 1 1
512 if defined $self->_prompt_text;
513 1 push @{ $self->_prompt_sections }, { title => $title, body => $body };
514 1 return $self;
515 }
516  
517 1 ▶sub add_bullets {
Subroutine add_bullets: called CC=2 SCAR=7.0
Pod undocumented
518 1 my ($self, $title, $bullets) = @_;
519 1 ▶ die "Cannot add POM sections when set_prompt() has been used"
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_prompt_text 0 1 1
520 if defined $self->_prompt_text;
521 1 push @{ $self->_prompt_sections }, { title => $title, bullets => $bullets };
522 1 return $self;
523 }
524  
525 1 ▶sub set_enter_fillers {
Subroutine set_enter_fillers: called CC=2 SCAR=7.1
Pod undocumented
526 1 my ($self, $fillers) = @_;
527 1 ▶ $self->_enter_fillers($fillers) if ref $fillers eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
if ref $fillers eq "HASH" 1 0 1
528 1 return $self;
529 }
530  
531 0 ▶sub set_exit_fillers {
Subroutine set_exit_fillers: not called CC=2 SCAR=17.9
Pod undocumented
532 0 my ($self, $fillers) = @_;
533 0 ▶ $self->_exit_fillers($fillers) if ref $fillers eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
if ref $fillers eq "HASH" 0 0 0
534 0 return $self;
535 }
536  
537 0 ▶sub add_enter_filler {
Subroutine add_enter_filler: not called CC=4 SCAR=30.0
Pod undocumented
538 0 my ($self, $lang, $fillers) = @_;
539 0 ▶ if ($lang && ref $fillers eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if ($lang and ref $fillers eq "ARRAY") 0 0 0
Condition0%0/3
$lang and ref $fillers eq "ARRAY"
!ll&&!rl&&r
000
MC/DC0%0/2
$lang and ref $fillers eq "ARRAY"
$lang ref $fillers eq "ARRAY"
Truth table0%0/3
A and B
A= $langB= ref $fillers eq "ARRAY"
ABresult
0X0
100
111
540 0 ▶ $self->_enter_fillers({}) unless defined $self->_enter_fillers;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->_enter_fillers 0 0 0
541 0 $self->_enter_fillers->{$lang} = $fillers;
542 }
543 0 return $self;
544 }
545  
546 1 ▶sub add_exit_filler {
Subroutine add_exit_filler: called CC=4 SCAR=15.2
Pod undocumented
547 1 my ($self, $lang, $fillers) = @_;
548 1 ▶ if ($lang && ref $fillers eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if ($lang and ref $fillers eq "ARRAY") 1 0 1
Condition33%1/3
$lang and ref $fillers eq "ARRAY"
!ll&&!rl&&r
001
MC/DC0%0/2
$lang and ref $fillers eq "ARRAY"
$lang ref $fillers eq "ARRAY"
Truth table33%1/3
A and B
A= $langB= ref $fillers eq "ARRAY"
ABresult
0X0
100
111
549 1 ▶ $self->_exit_fillers({}) unless defined $self->_exit_fillers;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->_exit_fillers 1 0 1
550 1 $self->_exit_fillers->{$lang} = $fillers;
551 }
552 1 return $self;
553 }
554  
555 0 ▶sub _render_prompt {
Subroutine _render_prompt: not called CC=3 SCAR=24.8
556 0 my ($self) = @_;
557 0 ▶ return $self->_prompt_text if defined $self->_prompt_text;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_prompt_text 0 0 0
558 0 ▶ return undef unless @{ $self->_prompt_sections };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->_prompt_sections;} 0 0 0
559 0 return _render_sections($self->_prompt_sections);
560 }
561  
562 13 ▶sub _render_system_prompt {
Subroutine _render_system_prompt: called CC=3 SCAR=11.3
563 13 my ($self) = @_;
564 13 ▶ return $self->_system_prompt if defined $self->_system_prompt;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_system_prompt 1 12 13
565 12 ▶ return undef unless @{ $self->_system_prompt_sections };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->_system_prompt_sections;} 12 0 12
566 0 return _render_sections($self->_system_prompt_sections);
567 }
568  
569 0 ▶sub _render_sections {
Subroutine _render_sections: not called CC=3 SCAR=24.8
570 0 my ($sections) = @_;
571 0 my @parts;
572 0 for my $sec (@$sections) {
573 0 ▶ if (exists $sec->{bullets}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $sec->{'bullets'}) { } 0 0 0
574 0 push @parts, "## $sec->{title}";
575 0 push @parts, map { "- $_" } @{ $sec->{bullets} };
576 } else {
577 0 push @parts, "## $sec->{title}";
578 0 push @parts, $sec->{body};
579 }
580 0 push @parts, '';
581 }
582 0 my $text = join("\n", @parts);
583 0 $text =~ s/\s+$//;
584 0 return $text;
585 }
586  
587 13 ▶sub to_hash {
Subroutine to_hash: called CC=15 SCAR=27.1
Pod undocumented
588 13 my ($self) = @_;
589 die "Context '" . $self->name . "' has no steps defined"
590 13 ▶ unless keys %{ $self->_steps };
Branch: 1 branch
BranchTrueFalseTotal
unless keys %{$self->_steps;} 0 13 13
591  
592 my %d = (
593 13 steps => [ map { $self->_steps->{$_}->to_hash } @{ $self->_step_order } ],
594 );
595  
596 13 ▶ $d{valid_contexts} = $self->_valid_contexts if defined $self->_valid_contexts;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_valid_contexts 3 10 13
597 13 ▶ $d{valid_steps} = $self->_valid_steps if defined $self->_valid_steps;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_valid_steps 1 12 13
598 13 ▶ $d{initial_step} = $self->_initial_step if defined $self->_initial_step;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_initial_step 0 13 13
599 13 ▶ $d{post_prompt} = $self->_post_prompt if defined $self->_post_prompt;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_post_prompt 1 12 13
600  
601 13 my $sp = $self->_render_system_prompt;
602 13 ▶ $d{system_prompt} = $sp if defined $sp;
Branch: 1 branch
BranchTrueFalseTotal
if defined $sp 1 12 13
603  
604 13 ▶ $d{consolidate} = JSON::true if $self->_consolidate;
Branch: 1 branch
BranchTrueFalseTotal
if $self->_consolidate 1 12 13
605 13 ▶ $d{full_reset} = JSON::true if $self->_full_reset;
Branch: 1 branch
BranchTrueFalseTotal
if $self->_full_reset 1 12 13
606 13 ▶ $d{user_prompt} = $self->_user_prompt if defined $self->_user_prompt;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_user_prompt 1 12 13
607 13 ▶ $d{isolated} = JSON::true if $self->_isolated;
Branch: 1 branch
BranchTrueFalseTotal
if $self->_isolated 1 12 13
608  
609 13 ▶ if (@{ $self->_prompt_sections }) {
Branch: 2 branches
BranchTrueFalseTotal
if (@{$self->_prompt_sections;}) { } 1 12 13
elsif (defined $self->_prompt_text) { } 1 11 12
610 1 $d{pom} = $self->_prompt_sections;
611 } elsif (defined $self->_prompt_text) {
612 1 $d{prompt} = $self->_prompt_text;
613 }
614  
615 13 ▶ $d{enter_fillers} = $self->_enter_fillers if defined $self->_enter_fillers;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_enter_fillers 1 12 13
616 13 ▶ $d{exit_fillers} = $self->_exit_fillers if defined $self->_exit_fillers;
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->_exit_fillers 1 12 13
617  
618 13 return \%d;
619 }
620  
621 # ==========================================================================
622 # ContextBuilder
623 # ==========================================================================
624 #
625 # SignalWire::Contexts::ContextBuilder
626 #
627 # Builder for multi-step, multi-context AI agent workflows.
628 #
629 # A ContextBuilder owns one or more Contexts; each Context owns an ordered
630 # list of Steps. Only one context and one step is active at a time. Per
631 # chat turn, the runtime injects the current step's instructions as a
632 # system message, then asks the LLM for a response.
633 #
634 # Native tools auto-injected by the runtime:
635 #
636 # When a step (or its enclosing context) declares valid_steps or
637 # valid_contexts, the runtime auto-injects two native tools so the
638 # model can navigate the flow:
639 #
640 # - next_step(step => enum) — present when valid_steps is set
641 # - change_context(context => enum) — present when valid_contexts is set
642 #
643 # A third native tool — gather_submit — is injected during gather_info
644 # questioning. These three names are reserved: ContextBuilder->validate
645 # rejects any agent that defines a SWAIG tool with one of these names.
646 # See %SignalWire::Contexts::RESERVED_NATIVE_TOOL_NAMES.
647 #
648 # Function whitelisting (Step->set_functions):
649 #
650 # Each step may declare a functions whitelist. The whitelist is applied
651 # in-memory at the start of each LLM turn. CRITICALLY: if a step does
652 # NOT declare a functions field, it INHERITS the previous step's active
653 # set. See Step->set_functions for details and examples.
654 #
655 package SignalWire::Contexts::ContextBuilder;
656 19 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
657 19 ▶use JSON ();
Subroutine BEGIN: called CC=1 SCAR=0.0
658 19 ▶use Scalar::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
659  
660 88 ▶has '_contexts' => (is => 'rw', default => sub { {} });
Subroutine __ANON__: called CC=1 SCAR=0.0
661 88 ▶has '_context_order' => (is => 'rw', default => sub { [] });
Subroutine __ANON__: called CC=1 SCAR=0.0
662 # Weak reference to the owning agent so validate() can check
663 # user-defined tool names against RESERVED_NATIVE_TOOL_NAMES. Set via
664 # attach_agent(); AgentBase->define_contexts wires this up automatically.
665 88 ▶has '_agent' => (is => 'rw', default => sub { undef });
Subroutine __ANON__: called CC=1 SCAR=0.0
666  
667 4 ▶sub attach_agent {
Subroutine attach_agent: called CC=2 SCAR=7.0
Pod undocumented
668 4 my ($self, $agent) = @_;
669 4 $self->_agent($agent);
670 4 ▶ Scalar::Util::weaken($self->{_agent}) if defined $agent;
Branch: 1 branch
BranchTrueFalseTotal
if defined $agent 4 0 4
671 4 return $self;
672 }
673  
674 0 ▶sub reset {
Subroutine reset: not called CC=1 SCAR=6.9
Pod undocumented
675 0 my ($self) = @_;
676 0 $self->_contexts({});
677 0 $self->_context_order([]);
678 0 return $self;
679 }
680  
681 18 ▶sub add_context {
Subroutine add_context: called CC=3 SCAR=11.0
Pod undocumented
682 18 my ($self, $name) = @_;
683 18 ▶ die "Context '$name' already exists" if exists $self->_contexts->{$name};
Branch: 1 branch
BranchTrueFalseTotal
if exists $self->_contexts->{$name} 1 17 18
684 die "Maximum number of contexts ($SignalWire::Contexts::MAX_CONTEXTS) exceeded"
685 17 ▶ if keys %{ $self->_contexts } >= $SignalWire::Contexts::MAX_CONTEXTS;
Branch: 1 branch
BranchTrueFalseTotal
if keys %{$self->_contexts;} >= $SignalWire::Contexts::MAX_CONTEXTS 0 17 17
686  
687 17 my $ctx = SignalWire::Contexts::Context->new(name => $name);
688 17 $self->_contexts->{$name} = $ctx;
689 17 push @{ $self->_context_order }, $name;
690 17 return $ctx;
691 }
692  
693 3 ▶sub get_context {
Subroutine get_context: called CC=1 SCAR=0.0
Pod undocumented
694 3 my ($self, $name) = @_;
695 3 return $self->_contexts->{$name};
696 }
697  
698 74 ▶sub has_contexts {
Subroutine has_contexts: called CC=2 SCAR=6.9
Pod undocumented
699 74 my ($self) = @_;
700 74 ▶ return scalar(keys %{ $self->_contexts }) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
scalar keys %{$self->_contexts;} ? : 3 71 74
701 }
702  
703 12 ▶sub validate {
Subroutine validate: called CC=41 SCAR=42.4
Pod undocumented
704 12 my ($self) = @_;
705 12 ▶ die "At least one context must be defined" unless keys %{ $self->_contexts };
Branch: 1 branch
BranchTrueFalseTotal
unless keys %{$self->_contexts;} 1 11 12
706  
707 # Single context must be "default"
708 11 ▶ if (keys %{ $self->_contexts } == 1) {
Branch: 1 branch
BranchTrueFalseTotal
if (keys %{$self->_contexts;} == 1) 10 1 11
709 10 my ($name) = keys %{ $self->_contexts };
710 10 ▶ die 'When using a single context, it must be named "default"'
Branch: 1 branch
BranchTrueFalseTotal
unless $name eq "default" 1 9 10
711 unless $name eq 'default';
712 }
713  
714 # Each context must have steps
715 10 for my $cname (keys %{ $self->_contexts }) {
716 11 my $ctx = $self->_contexts->{$cname};
717 die "Context '$cname' must have at least one step"
718 11 ▶ unless keys %{ $ctx->_steps };
Branch: 1 branch
BranchTrueFalseTotal
unless keys %{$ctx->_steps;} 1 10 11
719 }
720  
721 # Validate initial_step references a real step in the context
722 9 for my $cname (keys %{ $self->_contexts }) {
723 10 my $ctx = $self->_contexts->{$cname};
724 10 ▶ if (defined $ctx->_initial_step) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $ctx->_initial_step) 0 10 10
725 0 die "Context '$cname' has initial_step='${\$ctx->_initial_step}' "
726 . "but that step does not exist. Available steps: ["
727 0 . join(', ', map { "'$_'" } sort keys %{ $ctx->_steps })
728 . "]"
729 0 ▶ unless exists $ctx->_steps->{ $ctx->_initial_step };
Branch: 1 branch
BranchTrueFalseTotal
unless exists $ctx->_steps->{$ctx->_initial_step} 0 0 0
730 }
731 }
732  
733 # Validate step references in valid_steps
734 9 for my $cname (keys %{ $self->_contexts }) {
735 10 my $ctx = $self->_contexts->{$cname};
736 10 for my $sname (keys %{ $ctx->_steps }) {
737 12 my $step = $ctx->_steps->{$sname};
738 12 ▶ if (defined $step->_valid_steps) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $step->_valid_steps) 2 10 12
739 2 for my $vs (@{ $step->_valid_steps }) {
740 2 ▶ next if $vs eq 'next';
Branch: 1 branch
BranchTrueFalseTotal
if $vs eq "next" 1 1 2
741 die "Step '$sname' in context '$cname' references unknown step '$vs'"
742 1 ▶ unless exists $ctx->_steps->{$vs};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $ctx->_steps->{$vs} 1 0 1
743 }
744 }
745 }
746 }
747  
748 # Validate context references (context-level and step-level)
749 8 for my $cname (keys %{ $self->_contexts }) {
750 9 my $ctx = $self->_contexts->{$cname};
751 9 ▶ if (defined $ctx->_valid_contexts) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $ctx->_valid_contexts) 3 6 9
752 3 for my $vc (@{ $ctx->_valid_contexts }) {
753 die "Context '$cname' references unknown context '$vc'"
754 3 ▶ unless exists $self->_contexts->{$vc};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->_contexts->{$vc} 1 2 3
755 }
756 }
757 8 for my $sname (keys %{ $ctx->_steps }) {
758 10 my $step = $ctx->_steps->{$sname};
759 10 ▶ if (defined $step->_valid_contexts) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $step->_valid_contexts) 0 10 10
760 0 for my $vc (@{ $step->_valid_contexts }) {
761 die "Step '$sname' in context '$cname' references unknown context '$vc'"
762 0 ▶ unless exists $self->_contexts->{$vc};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->_contexts->{$vc} 0 0 0
763 }
764 }
765 }
766 }
767  
768 # Validate gather_info
769 7 for my $cname (keys %{ $self->_contexts }) {
770 8 my $ctx = $self->_contexts->{$cname};
771 8 for my $sname (keys %{ $ctx->_steps }) {
772 10 my $step = $ctx->_steps->{$sname};
773 10 ▶ if (defined $step->_gather_info) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $step->_gather_info) 3 7 10
774 die "Step '$sname' in context '$cname' has gather_info with no questions"
775 3 ▶ unless @{ $step->_gather_info->_questions };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$step->_gather_info->_questions;} 1 2 3
776  
777 2 my %seen;
778 2 for my $q (@{ $step->_gather_info->_questions }) {
779 1 die "Step '$sname' in context '$cname' has duplicate gather_info question key '${\$q->key}'"
780 3 ▶ if $seen{ $q->key }++;
Branch: 1 branch
BranchTrueFalseTotal
if $seen{$q->key}++ 1 2 3
781 }
782  
783 1 my $action = $step->_gather_info->_completion_action;
784 1 ▶ if (defined $action) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $action) 1 0 1
785 1 ▶ if ($action eq 'next_step') {
Branch: 2 branches
BranchTrueFalseTotal
if ($action eq 'next_step') { } 1 0 1
elsif (not exists $ctx->_steps->{$action}) { } 0 0 0
786 1 my $idx;
787 1 my @order = @{ $ctx->_step_order };
788 1 for my $i (0 .. $#order) {
789 1 ▶ if ($order[$i] eq $sname) { $idx = $i; last }
Branch: 1 branch
BranchTrueFalseTotal
if ($order[$i] eq $sname) 1 0 1
790 }
791 1 ▶ die "Step '$sname' in context '$cname' has gather_info "
Branch: 1 branch
BranchTrueFalseTotal
if defined $idx and $idx >= $#order 1 0 1
Condition33%1/3
defined $idx and $idx >= $#order
!ll&&!rl&&r
001
MC/DC0%0/2
defined $idx and $idx >= $#order
defined $idx $idx >= $#order
Truth table33%1/3
A and B
A= defined $idxB= $idx >= $#order
ABresult
0X0
100
111
792 . "completion_action='next_step' but it is the last "
793 . "step in the context. Either "
794 . "(1) add another step after '$sname', "
795 . "(2) set completion_action to the name of an "
796 . "existing step in this context to jump to it, or "
797 . "(3) set completion_action=undef (default) to "
798 . "stay in '$sname' after gathering completes."
799 if defined $idx && $idx >= $#order;
800 } elsif (!exists $ctx->_steps->{$action}) {
801 0 my @available = sort keys %{ $ctx->_steps };
802 die "Step '$sname' in context '$cname' has gather_info "
803 . "completion_action='$action' but '$action' is not "
804 . "a step in this context. Valid options: "
805 . "'next_step' (advance to the next sequential "
806 . "step), undef (stay in the current step), or "
807 0 . "one of [" . join(', ', map { "'$_'" } @available) . "].";
808 }
809 }
810 }
811 }
812 }
813  
814 # Validate that user-defined tools do not collide with reserved
815 # native tool names. The runtime auto-injects next_step /
816 # change_context / gather_submit when contexts/steps are present, so
817 # user tools sharing those names would never be called.
818 4 ▶ if (defined $self->_agent && $self->_agent->can('list_tool_names')) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->_agent and $self->_agent->can("list_tool_names")) 1 3 4
Condition66%2/3
defined $self->_agent and $self->_agent->can("list_tool_names")
!ll&&!rl&&r
301
MC/DC50%1/2
defined $self->_agent and $self->_agent->can("list_tool_names")
defined $self->_agent $self->_agent->can("list_tool_names")
Truth table66%2/3
A and B
A= defined $self->_agentB= $self->_agent->can("list_tool_names")
ABresult
0X0
100
111
819 1 my @registered = $self->_agent->list_tool_names;
820 1 my @colliding;
821 1 for my $name (@registered) {
822 push @colliding, $name
823 0 ▶ if exists $SignalWire::Contexts::RESERVED_NATIVE_TOOL_NAMES{$name};
Branch: 1 branch
BranchTrueFalseTotal
if exists $SignalWire::Contexts::RESERVED_NATIVE_TOOL_NAMES{$name} 0 0 0
824 }
825 1 ▶ if (@colliding) {
Branch: 1 branch
BranchTrueFalseTotal
if (@colliding) 0 1 1
826 0 my @sorted = sort @colliding;
827 0 my @reserved = sort keys %SignalWire::Contexts::RESERVED_NATIVE_TOOL_NAMES;
828 die "Tool name(s) ["
829 0 . join(', ', map { "'$_'" } @sorted)
830 . "] collide with reserved native tools auto-injected by "
831 . "contexts/steps. The names ["
832 0 . join(', ', map { "'$_'" } @reserved)
833 . "] are reserved and cannot be used for user-defined SWAIG "
834 . "tools when contexts/steps are in use. Rename your "
835 . "tool(s) to avoid the collision.";
836 }
837 }
838 }
839  
840 12 ▶sub to_hash {
Subroutine to_hash: called CC=2 SCAR=6.9
Pod undocumented
841 12 my ($self) = @_;
842 12 $self->validate;
843  
844 4 my %result;
845 4 for my $cname (@{ $self->_context_order }) {
846 5 $result{$cname} = $self->_contexts->{$cname}->to_hash;
847 }
848 4 return \%result;
849 }
850  
851 # Back to main package
852 package SignalWire::Contexts;
853  
854 # Python parity: signalwire.core.contexts.create_simple_context(name='default')
855 # is a module-level free function. Perl invocation forms supported:
856 # - SignalWire::Contexts::create_simple_context('mycontext') # free fn
857 # - SignalWire::Contexts->create_simple_context('mycontext') # class method
858 # Both forms collapse to a single optional ``$name`` argument.
859 4 ▶sub create_simple_context {
Subroutine create_simple_context: called CC=5 SCAR=16.1
Pod undocumented
860 4 my ($name) = @_;
861 4 ▶ if (defined $name && !ref($name) && $name eq __PACKAGE__) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $name and not ref $name and $name eq __PACKAGE__) 2 2 4
Condition83%5/6
defined $name and not ref $name and $name eq __PACKAGE__
!ll&&!rl&&r
112
defined $name and not ref $name
!ll&&!rl&&r
103
MC/DC66%2/3
defined $name and not ref $name and $name eq __PACKAGE__
defined $name not ref $name $name eq __PACKAGE__
Truth table75%3/4
A and not(B) and C
A= defined $nameB= not ref $nameC= $name eq __PACKAGE__
ABCresult
0XX0
10X0
1100
1111
862 # Class-method invocation form — drop the receiver, shift remaining.
863 2 shift;
864 2 $name = $_[0];
865 }
866 4 ▶ $name //= 'default';
Condition100%2/2
$name //= "default"
l!l
22
MC/DC100%1/1
$name //= "default"
$name
Truth table100%2/2
A
A= $name
Aresult
11
00
867 4 return SignalWire::Contexts::Context->new(name => $name);
868 }
869  
870 19 1;
« blib/lib/SignalWire/Utils/UrlValidator.pm ↑ Summary scripts/enumerate_surface.pl »