@signalwire/sdk 3.7.2 → 3.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/CHANGELOG.md +154 -0
  2. package/README.md +1 -0
  3. package/dist/AgentBase.d.ts +107 -2
  4. package/dist/AgentBase.js +259 -13
  5. package/dist/AgentBase.js.map +1 -1
  6. package/dist/AiEvents.d.ts +70 -0
  7. package/dist/AiEvents.js +94 -0
  8. package/dist/AiEvents.js.map +1 -0
  9. package/dist/ContextBuilder.d.ts +181 -9
  10. package/dist/ContextBuilder.js +407 -9
  11. package/dist/ContextBuilder.js.map +1 -1
  12. package/dist/FunctionResult.d.ts +129 -0
  13. package/dist/FunctionResult.js +170 -0
  14. package/dist/FunctionResult.js.map +1 -1
  15. package/dist/PostPrompt.d.ts +19 -0
  16. package/dist/PostPrompt.js +43 -0
  17. package/dist/PostPrompt.js.map +1 -1
  18. package/dist/SWMLService.d.ts +97 -1
  19. package/dist/SWMLService.js +129 -2
  20. package/dist/SWMLService.js.map +1 -1
  21. package/dist/SemanticGate.d.ts +61 -1
  22. package/dist/SemanticGate.js +108 -15
  23. package/dist/SemanticGate.js.map +1 -1
  24. package/dist/SwaigFunction.d.ts +85 -9
  25. package/dist/SwaigFunction.js +214 -58
  26. package/dist/SwaigFunction.js.map +1 -1
  27. package/dist/ToolMiddleware.d.ts +82 -0
  28. package/dist/ToolMiddleware.js +131 -0
  29. package/dist/ToolMiddleware.js.map +1 -0
  30. package/dist/TypeInference.d.ts +1 -1
  31. package/dist/TypeInference.js.map +1 -1
  32. package/dist/cli/tsdocs/api-index.json +1 -1
  33. package/dist/cli/tsdocs/topics.js +24 -4
  34. package/dist/cli/tsdocs/topics.js.map +1 -1
  35. package/dist/index.d.ts +22 -8
  36. package/dist/index.js +15 -5
  37. package/dist/index.js.map +1 -1
  38. package/dist/llms.txt +1 -0
  39. package/dist/patterns/Proposal.d.ts +146 -0
  40. package/dist/patterns/Proposal.js +212 -0
  41. package/dist/patterns/Proposal.js.map +1 -0
  42. package/dist/patterns/RequestList.d.ts +136 -0
  43. package/dist/patterns/RequestList.js +169 -0
  44. package/dist/patterns/RequestList.js.map +1 -0
  45. package/dist/skills/SkillBase.d.ts +24 -1
  46. package/dist/skills/SkillBase.js +12 -1
  47. package/dist/skills/SkillBase.js.map +1 -1
  48. package/dist/speech/numbers.d.ts +66 -0
  49. package/dist/speech/numbers.js +281 -0
  50. package/dist/speech/numbers.js.map +1 -0
  51. package/dist/speech/spelling.d.ts +71 -0
  52. package/dist/speech/spelling.js +294 -0
  53. package/dist/speech/spelling.js.map +1 -0
  54. package/dist/testing/CallSimulator.d.ts +281 -0
  55. package/dist/testing/CallSimulator.js +666 -0
  56. package/dist/testing/CallSimulator.js.map +1 -0
  57. package/docs/agent-guide.md +2 -2
  58. package/docs/api-reference.md +277 -20
  59. package/docs/architecture.md +8 -4
  60. package/docs/cli-guide.md +2 -0
  61. package/docs/contexts-guide.md +45 -3
  62. package/docs/conversation_patterns.md +257 -0
  63. package/docs/mcp_integration.md +1 -1
  64. package/docs/programmatically_governed_inference.md +1 -1
  65. package/docs/swaig-reference.md +95 -3
  66. package/package.json +1 -1
@@ -4,6 +4,31 @@
4
4
  * Contexts contain ordered Steps, each with prompt text/POM sections,
5
5
  * completion criteria, function restrictions, and navigation rules.
6
6
  */
7
+ /** The most digits an expected answer can name. */
8
+ export declare const MAX_EXPECTED_DIGITS = 64;
9
+ /**
10
+ * An `expected_answer` as the platform reads it: an exact count of digits, or
11
+ * a range. {@link expectedAnswer} builds one.
12
+ */
13
+ export type ExpectedAnswer = {
14
+ digits: number;
15
+ } | {
16
+ min_digits: number;
17
+ max_digits: number;
18
+ };
19
+ /**
20
+ * An `expected_answer` as the platform reads it: `{ digits: N }`, or
21
+ * `{ min_digits: a, max_digits: b }` with a at most b, each count from 1 to
22
+ * 64. The platform logs and ignores any other shape.
23
+ * @param digits - The exact number of digits.
24
+ * @param opts - Or, without `digits`, the fewest and most digits.
25
+ * @returns The expected answer.
26
+ * @throws {Error} For a shape or count the platform would ignore.
27
+ */
28
+ export declare function expectedAnswer(digits?: number, opts?: {
29
+ minDigits?: number;
30
+ maxDigits?: number;
31
+ }): ExpectedAnswer;
7
32
  /**
8
33
  * Valid values for a step's or context's `history` visibility mode.
9
34
  *
@@ -73,6 +98,8 @@ export interface StepDict {
73
98
  skip_to_next_step?: boolean;
74
99
  /** Optional history visibility mode; present only when explicitly set. */
75
100
  history?: HistoryMode;
101
+ /** Optional number of digits the caller's answer has, for the recognizer. */
102
+ expected_answer?: ExpectedAnswer;
76
103
  /** Optional prompt-reset directives for this step. */
77
104
  reset?: {
78
105
  system_prompt?: string;
@@ -138,9 +165,15 @@ export declare class GatherQuestion {
138
165
  * unset — it is emitted to SWML so it can override an isolated gather.
139
166
  */
140
167
  isolated?: boolean;
168
+ /**
169
+ * The number of digits the answer has, for the recognizer: while this
170
+ * question is asked, it replaces the step's expected answer.
171
+ */
172
+ expectedAnswer?: ExpectedAnswer;
141
173
  /**
142
174
  * Creates a new GatherQuestion.
143
- * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions/isolated.
175
+ * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions/isolated/expectedAnswer.
176
+ * @throws {Error} For an `expectedAnswer` the platform would ignore.
144
177
  */
145
178
  constructor(opts: {
146
179
  key: string;
@@ -150,6 +183,7 @@ export declare class GatherQuestion {
150
183
  prompt?: string;
151
184
  functions?: string[];
152
185
  isolated?: boolean;
186
+ expectedAnswer?: ExpectedAnswer;
153
187
  });
154
188
  /**
155
189
  * Serializes this question to a plain object for SWML output.
@@ -192,6 +226,7 @@ export declare class GatherInfo {
192
226
  prompt?: string;
193
227
  functions?: string[];
194
228
  isolated?: boolean;
229
+ expectedAnswer?: ExpectedAnswer;
195
230
  }): this;
196
231
  /**
197
232
  * Returns all questions in this gather operation.
@@ -230,6 +265,8 @@ export declare class Step {
230
265
  private text;
231
266
  private stepCriteria;
232
267
  private functions;
268
+ /** The recognizer's hint for a number the caller is asked for. */
269
+ private _expectedAnswer;
233
270
  private validSteps;
234
271
  private validContexts;
235
272
  private sections;
@@ -402,6 +439,13 @@ export declare class Step {
402
439
  prompt?: string;
403
440
  functions?: string[];
404
441
  isolated?: boolean;
442
+ /**
443
+ * The number of digits the answer has, for the recognizer, as
444
+ * {@link expectedAnswer} builds it: `{ digits: 5 }` or
445
+ * `{ min_digits: 4, max_digits: 6 }`. While this question is asked, it
446
+ * replaces the step's.
447
+ */
448
+ expectedAnswer?: ExpectedAnswer;
405
449
  }): this;
406
450
  /**
407
451
  * Returns the gather info for this step, if any.
@@ -418,6 +462,47 @@ export declare class Step {
418
462
  * @internal
419
463
  */
420
464
  getStepValidContexts(): string[] | null;
465
+ /**
466
+ * Tell the recognizer how many digits the caller's answer in this step has,
467
+ * such as a ZIP code or a PIN.
468
+ *
469
+ * The recognizer ends its wait for a number once the caller has said that
470
+ * many digits. A gather question's own expected answer replaces this while
471
+ * that question is asked. Pass `digits` for an exact count, or `minDigits`
472
+ * and `maxDigits` for a range, each from 1 to 64. Sent as `expected_answer`;
473
+ * it needs a platform release that has it.
474
+ * @param digits - The exact number of digits.
475
+ * @param opts - Or, without `digits`, the fewest and most digits.
476
+ * @returns This step for chaining.
477
+ * @throws {Error} For a count or combination the platform would ignore.
478
+ */
479
+ setExpectedAnswer(digits?: number, opts?: {
480
+ minDigits?: number;
481
+ maxDigits?: number;
482
+ }): this;
483
+ /**
484
+ * Whether this step sets its own function list (an array or a string
485
+ * sentinel such as `'none'`), rather than keeping the one before it.
486
+ * @internal
487
+ */
488
+ _hasFunctionList(): boolean;
489
+ /**
490
+ * The step's own function list: null when it inherits the list before it,
491
+ * empty for `'none'`.
492
+ * @internal
493
+ */
494
+ _offeredFunctions(): string[] | null;
495
+ /**
496
+ * Whether the step has a reset, which makes it terminal.
497
+ * @internal
498
+ */
499
+ _hasReset(): boolean;
500
+ /**
501
+ * What the model reads in this step, as `[where, text, tools also offered
502
+ * there]`: its text, its criteria, and its gather questions.
503
+ * @internal
504
+ */
505
+ _modelTexts(): Array<[string, string, string[]]>;
421
506
  /**
422
507
  * Returns this step's function whitelist as an array of tool NAMES to
423
508
  * validate, or null when there is nothing to validate. A string value
@@ -432,25 +517,42 @@ export declare class Step {
432
517
  */
433
518
  clearSections(): this;
434
519
  /**
435
- * Sets the system prompt to use when resetting context at this step.
520
+ * Set the system prompt this step's reset loads.
521
+ *
522
+ * A step with any reset setting is terminal: when the call enters it, the
523
+ * platform runs the reset in place of the step's text, and step mode ends
524
+ * there. Use it for a step that hands the call over to a new prompt.
436
525
  * @param systemPrompt - The replacement system prompt text.
437
526
  * @returns This step for chaining.
438
527
  */
439
528
  setResetSystemPrompt(systemPrompt: string): this;
440
529
  /**
441
- * Sets the user prompt to use when resetting context at this step.
530
+ * Set the user message this step's reset adds.
531
+ *
532
+ * A step with any reset setting is terminal: when the call enters it, the
533
+ * platform runs the reset in place of the step's text, and step mode ends
534
+ * there. Use it for a step that hands the call over to a new prompt.
442
535
  * @param userPrompt - The replacement user prompt text.
443
536
  * @returns This step for chaining.
444
537
  */
445
538
  setResetUserPrompt(userPrompt: string): this;
446
539
  /**
447
- * Sets whether to consolidate conversation history when resetting at this step.
540
+ * Set whether this step's reset consolidates the conversation into a summary.
541
+ *
542
+ * A step with any reset setting is terminal: when the call enters it, the
543
+ * platform runs the reset in place of the step's text, and step mode ends
544
+ * there. Use it for a step that hands the call over to a new prompt.
448
545
  * @param consolidate - Whether to consolidate.
449
546
  * @returns This step for chaining.
450
547
  */
451
548
  setResetConsolidate(consolidate: boolean): this;
452
549
  /**
453
- * Sets whether to perform a full conversation reset at this step.
550
+ * Set whether this step's reset replaces the system prompt, seeded with the
551
+ * consolidated summary, rather than adding to it.
552
+ *
553
+ * A step with any reset setting is terminal: when the call enters it, the
554
+ * platform runs the reset in place of the step's text, and step mode ends
555
+ * there. Use it for a step that hands the call over to a new prompt.
454
556
  * @param fullReset - Whether to fully reset.
455
557
  * @returns This step for chaining.
456
558
  */
@@ -608,8 +710,9 @@ export declare class Context {
608
710
  * Mark this context as isolated — entering it wipes conversation history.
609
711
  *
610
712
  * When `isolated=true` and the context is entered via change_context, the
611
- * runtime wipes the conversation array. The model starts fresh with only
612
- * the new context's systemPrompt + step instructions, with no memory of
713
+ * runtime calls ai_conversation_restart(), which drops every conversation
714
+ * entry but the first, the base system prompt. The model starts fresh with
715
+ * the base prompt and the new context's step instructions, with no memory of
613
716
  * prior turns.
614
717
  *
615
718
  * EXCEPTION — `reset` overrides the wipe:
@@ -710,6 +813,17 @@ export declare class Context {
710
813
  getValidContexts(): string[] | null;
711
814
  private renderPrompt;
712
815
  private renderSystemPrompt;
816
+ /**
817
+ * The context's prompt, which goes before every step's text.
818
+ * @internal
819
+ */
820
+ _modelPrompt(): string | null;
821
+ /**
822
+ * The reset settings that do nothing because the context has no system
823
+ * prompt: the platform runs a context's reset only with one.
824
+ * @internal
825
+ */
826
+ _inertResetSettings(): string[];
713
827
  private renderSections;
714
828
  /**
715
829
  * Serializes this context and all its steps to a plain object for SWML output.
@@ -739,8 +853,8 @@ export declare class Context {
739
853
  * - `next_step(step: enum)` — present when validSteps is set
740
854
  * - `change_context(context: enum)` — present when validContexts is set
741
855
  *
742
- * Their `enum` schemas are rewritten on every turn to match whatever
743
- * validSteps / validContexts apply to the current step. You do NOT need
856
+ * Their `enum` schemas are rewritten when a step loads, to match whatever
857
+ * validSteps / validContexts apply to that step. You do NOT need
744
858
  * to define these tools yourself; they appear automatically.
745
859
  *
746
860
  * A third native tool — `gather_submit` — is injected during gather_info
@@ -800,6 +914,12 @@ export declare class Context {
800
914
  export declare class ContextBuilder {
801
915
  private contexts;
802
916
  private contextOrder;
917
+ /**
918
+ * Tools already reported as offered by no step, so a render on every request
919
+ * doesn't repeat it. The agent shares its own set, so its per-request copies
920
+ * don't repeat it either.
921
+ */
922
+ private unofferedWarned;
803
923
  private agent;
804
924
  /**
805
925
  * Attach an agent reference so validate() can check user tool names
@@ -808,6 +928,12 @@ export declare class ContextBuilder {
808
928
  * @internal
809
929
  */
810
930
  attachAgent(agent: unknown): this;
931
+ /**
932
+ * Record the tools reported as offered by no step in `warned`, a set the
933
+ * agent keeps for itself and its per-request copies.
934
+ * @internal
935
+ */
936
+ _shareUnofferedWarnings(warned: Set<string>): this;
811
937
  /**
812
938
  * Removes all contexts, returning the builder to its initial state.
813
939
  * Use this in a dynamic config callback when you need to rebuild
@@ -836,6 +962,40 @@ export declare class ContextBuilder {
836
962
  * @throws Error if validation fails.
837
963
  */
838
964
  validate(): void;
965
+ /**
966
+ * The steps whose function list offers `functionName`, as
967
+ * `[context, step]` pairs in order, including a gather question's functions.
968
+ *
969
+ * A step without `setFunctions()` keeps whatever was active before it, so it
970
+ * isn't counted: what it offers depends on the step the call came from. The
971
+ * platform's reply to a call of a tool the current step doesn't offer names
972
+ * the same steps.
973
+ * @param functionName - The function's name.
974
+ * @returns The `[context name, step name]` pairs, empty when no step lists it.
975
+ */
976
+ stepsOffering(functionName: string): Array<[string, string]>;
977
+ /**
978
+ * Log, once each, reset settings that don't do what they read as: a step
979
+ * with a reset is terminal, so its text never runs; and a context's
980
+ * consolidate, full_reset and user_prompt act only with a system prompt,
981
+ * whose presence runs the context's reset.
982
+ */
983
+ private warnInertResets;
984
+ /**
985
+ * Log, once each, a registered tool named where the step doesn't offer it:
986
+ * in its text, its criteria, its context's prompt (which goes before every
987
+ * step's text), a gather question, or a gate's output on one of its tools.
988
+ * The model reads the name and may call a tool it doesn't have. A step
989
+ * without a function list is skipped: what it offers depends on the step
990
+ * before it.
991
+ */
992
+ private warnToolMentions;
993
+ /**
994
+ * Log, once per tool, a tool no step can offer: when every step lists its
995
+ * functions and none lists it, the model never gets it, unless a function
996
+ * result turns it on.
997
+ */
998
+ private warnUnofferedTools;
839
999
  /**
840
1000
  * Validates and serializes all contexts to a plain object for SWML output.
841
1001
  * @returns A dictionary mapping context names to their serialized representations.
@@ -853,4 +1013,16 @@ export declare class ContextBuilder {
853
1013
  * @returns A new Context instance.
854
1014
  */
855
1015
  export declare function createSimpleContext(name?: string): Context;
1016
+ /**
1017
+ * The tool names `text` names.
1018
+ *
1019
+ * A name with an underscore, such as `place_order`, counts as a whole word
1020
+ * anywhere. A one-word name, such as `help`, counts only in backticks or before
1021
+ * "(", since it's also an ordinary word.
1022
+ *
1023
+ * @param text - The text: a step's, a prompt's or a tool result's.
1024
+ * @param tools - The tool names to look for.
1025
+ * @returns The names it finds.
1026
+ */
1027
+ export declare function namedTools(text: string | null | undefined, tools: Iterable<string>): Set<string>;
856
1028
  export {};