@signalwire/sdk 3.7.2 → 3.10.3

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 (67) hide show
  1. package/CHANGELOG.md +201 -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 +215 -14
  10. package/dist/ContextBuilder.js +441 -14
  11. package/dist/ContextBuilder.js.map +1 -1
  12. package/dist/FunctionResult.d.ts +146 -1
  13. package/dist/FunctionResult.js +188 -2
  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 +148 -0
  40. package/dist/patterns/Proposal.js +214 -0
  41. package/dist/patterns/Proposal.js.map +1 -0
  42. package/dist/patterns/RequestList.d.ts +138 -0
  43. package/dist/patterns/RequestList.js +171 -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 +391 -0
  55. package/dist/testing/CallSimulator.js +966 -0
  56. package/dist/testing/CallSimulator.js.map +1 -0
  57. package/docs/agent-guide.md +2 -2
  58. package/docs/api-reference.md +279 -22
  59. package/docs/architecture.md +8 -4
  60. package/docs/cli-guide.md +2 -0
  61. package/docs/contexts-guide.md +75 -4
  62. package/docs/conversation_patterns.md +257 -0
  63. package/docs/mcp_integration.md +1 -1
  64. package/docs/pgi_agent_guide.md +5 -0
  65. package/docs/programmatically_governed_inference.md +2 -2
  66. package/docs/swaig-reference.md +98 -6
  67. package/package.json +1 -1
@@ -0,0 +1,138 @@
1
+ /**
2
+ * What the caller asked for while the agent was busy with something else.
3
+ *
4
+ * A caller in the middle of one task often asks for another: "and can you also
5
+ * check my balance?" Taking it up at once loses the first task; ignoring it
6
+ * loses the second. A tool notes the request, and the agent tells the caller
7
+ * it's noted for right after this. When the first task is done, the step's
8
+ * text, which shows the list, has the agent take up the next one.
9
+ *
10
+ * The list lives in the call's `global_data`, so it lasts for the call and a
11
+ * step's text can show it, as `${global_data.<key>_text}`.
12
+ */
13
+ import { FunctionResult } from '../FunctionResult.js';
14
+ /** One request the caller made. */
15
+ export interface NotedRequest {
16
+ /** The kind of request, one of the app's (it picks the opener). */
17
+ kind: string;
18
+ /** What it's about, in a few words. */
19
+ about: string;
20
+ }
21
+ /** Options for a {@link RequestList}. */
22
+ export interface RequestListOptions {
23
+ /**
24
+ * How the agent opens each kind of request when it takes it up, keyed by
25
+ * kind, with `{about}` for what it's about. A kind without one opens with
26
+ * what it's about.
27
+ */
28
+ openers?: Record<string, string>;
29
+ /** The first line of the list's text. Default "Noted for right after this:". */
30
+ heading?: string;
31
+ }
32
+ /**
33
+ * The caller's requests to come back to, in the order they asked.
34
+ *
35
+ * @example
36
+ * ```ts
37
+ * import { AgentBase, RequestList } from '@signalwire/sdk';
38
+ *
39
+ * const agent = new AgentBase({ name: 'bank' });
40
+ * const later = new RequestList('later', {
41
+ * openers: {
42
+ * balance: 'You also asked about your balance.',
43
+ * question: 'You had a question: {about}.',
44
+ * },
45
+ * });
46
+ *
47
+ * agent.setGlobalData(later.defaults());
48
+ * agent.defineTool({
49
+ * name: 'note_request',
50
+ * description: 'Note a request to come back to',
51
+ * parameters: {
52
+ * type: 'object',
53
+ * properties: { kind: { type: 'string' }, about: { type: 'string' } },
54
+ * required: ['kind', 'about'],
55
+ * },
56
+ * handler: (args, rawData) => later.note(rawData, String(args.kind), String(args.about)),
57
+ * });
58
+ * const ctx = agent.defineContexts().addContext('default');
59
+ * ctx.addStep('take_order').setText("Take the caller's order.\n\n${global_data.later_text}");
60
+ * ```
61
+ *
62
+ * The model hears of each new request in the tool result. Current platform
63
+ * releases expand the step's text again when the list changes, so it shows at
64
+ * the next request. Earlier releases, and a realtime model, keep the list from
65
+ * the step's entry: return `refreshStep()` with the note there to show it at
66
+ * once.
67
+ */
68
+ export declare class RequestList {
69
+ /** The `global_data` key the list is kept under. */
70
+ globalKey: string;
71
+ /** The `global_data` key its text for step text is kept under: `<globalKey>_text`. */
72
+ textKey: string;
73
+ /** How the agent opens each kind of request. */
74
+ openers: Record<string, string>;
75
+ /** The first line of the list's text. */
76
+ heading: string;
77
+ /**
78
+ * @param globalKey - The `global_data` key the list is kept under. Its text
79
+ * for step text is kept under `<globalKey>_text`.
80
+ * @param opts - `openers` and `heading`.
81
+ */
82
+ constructor(globalKey: string, opts?: RequestListOptions);
83
+ /**
84
+ * The `global_data` to start a call with, an empty list, so step text that
85
+ * shows it has a value before anything is noted.
86
+ * @returns The global data.
87
+ */
88
+ defaults(): Record<string, unknown>;
89
+ /**
90
+ * The requests a call has noted, oldest first, from its request's `global_data`.
91
+ * @param rawData - The call's request.
92
+ * @returns The requests.
93
+ */
94
+ pending(rawData: Record<string, unknown> | null | undefined): NotedRequest[];
95
+ /**
96
+ * Note a request to come back to, and tell the model so.
97
+ *
98
+ * The model gets "Noted for right after this: <about>.", with a tool prompt to
99
+ * tell the caller and carry on with what it was doing. The same request noted
100
+ * twice is kept once.
101
+ *
102
+ * @param rawData - The noting call's request.
103
+ * @param kind - The kind of request, one of the app's (it picks the opener).
104
+ * @param about - What it's about, in a few words.
105
+ * @param result - A result to add to.
106
+ * @returns The result.
107
+ */
108
+ note(rawData: Record<string, unknown> | null | undefined, kind: string, about: string, result?: FunctionResult): FunctionResult;
109
+ /**
110
+ * The oldest request not yet taken up, with its `opener`, or null.
111
+ * @param rawData - The call's request.
112
+ * @returns The request.
113
+ */
114
+ next(rawData: Record<string, unknown> | null | undefined): (NotedRequest & {
115
+ opener: string;
116
+ }) | null;
117
+ /**
118
+ * Remove the oldest request, once it has been taken up.
119
+ * @param rawData - The call's request.
120
+ * @param result - A result to add to.
121
+ * @returns The result.
122
+ */
123
+ done(rawData: Record<string, unknown> | null | undefined, result?: FunctionResult): FunctionResult;
124
+ /**
125
+ * How the agent opens a request when it takes it up.
126
+ * @param request - The request.
127
+ * @returns The opener.
128
+ */
129
+ opener(request: Partial<NotedRequest>): string;
130
+ /**
131
+ * The list as step text: the heading and one numbered line a request, or ""
132
+ * when there are none.
133
+ * @param requests - The requests.
134
+ * @returns The text.
135
+ */
136
+ asText(requests: readonly NotedRequest[]): string;
137
+ private store;
138
+ }
@@ -0,0 +1,171 @@
1
+ /**
2
+ * What the caller asked for while the agent was busy with something else.
3
+ *
4
+ * A caller in the middle of one task often asks for another: "and can you also
5
+ * check my balance?" Taking it up at once loses the first task; ignoring it
6
+ * loses the second. A tool notes the request, and the agent tells the caller
7
+ * it's noted for right after this. When the first task is done, the step's
8
+ * text, which shows the list, has the agent take up the next one.
9
+ *
10
+ * The list lives in the call's `global_data`, so it lasts for the call and a
11
+ * step's text can show it, as `${global_data.<key>_text}`.
12
+ */
13
+ import { FunctionResult } from '../FunctionResult.js';
14
+ /**
15
+ * The caller's requests to come back to, in the order they asked.
16
+ *
17
+ * @example
18
+ * ```ts
19
+ * import { AgentBase, RequestList } from '@signalwire/sdk';
20
+ *
21
+ * const agent = new AgentBase({ name: 'bank' });
22
+ * const later = new RequestList('later', {
23
+ * openers: {
24
+ * balance: 'You also asked about your balance.',
25
+ * question: 'You had a question: {about}.',
26
+ * },
27
+ * });
28
+ *
29
+ * agent.setGlobalData(later.defaults());
30
+ * agent.defineTool({
31
+ * name: 'note_request',
32
+ * description: 'Note a request to come back to',
33
+ * parameters: {
34
+ * type: 'object',
35
+ * properties: { kind: { type: 'string' }, about: { type: 'string' } },
36
+ * required: ['kind', 'about'],
37
+ * },
38
+ * handler: (args, rawData) => later.note(rawData, String(args.kind), String(args.about)),
39
+ * });
40
+ * const ctx = agent.defineContexts().addContext('default');
41
+ * ctx.addStep('take_order').setText("Take the caller's order.\n\n${global_data.later_text}");
42
+ * ```
43
+ *
44
+ * The model hears of each new request in the tool result. Current platform
45
+ * releases expand the step's text again when the list changes, so it shows at
46
+ * the next request. Earlier releases, and a realtime model, keep the list from
47
+ * the step's entry: return `refreshStep()` with the note there to show it at
48
+ * once.
49
+ */
50
+ export class RequestList {
51
+ /** The `global_data` key the list is kept under. */
52
+ globalKey;
53
+ /** The `global_data` key its text for step text is kept under: `<globalKey>_text`. */
54
+ textKey;
55
+ /** How the agent opens each kind of request. */
56
+ openers;
57
+ /** The first line of the list's text. */
58
+ heading;
59
+ /**
60
+ * @param globalKey - The `global_data` key the list is kept under. Its text
61
+ * for step text is kept under `<globalKey>_text`.
62
+ * @param opts - `openers` and `heading`.
63
+ */
64
+ constructor(globalKey, opts = {}) {
65
+ this.globalKey = globalKey;
66
+ this.textKey = `${globalKey}_text`;
67
+ this.openers = { ...(opts.openers ?? {}) };
68
+ this.heading = opts.heading ?? 'Noted for right after this:';
69
+ }
70
+ /**
71
+ * The `global_data` to start a call with, an empty list, so step text that
72
+ * shows it has a value before anything is noted.
73
+ * @returns The global data.
74
+ */
75
+ defaults() {
76
+ return { [this.globalKey]: [], [this.textKey]: '' };
77
+ }
78
+ /**
79
+ * The requests a call has noted, oldest first, from its request's `global_data`.
80
+ * @param rawData - The call's request.
81
+ * @returns The requests.
82
+ */
83
+ pending(rawData) {
84
+ if (!isRecord(rawData))
85
+ return [];
86
+ const globalData = rawData['global_data'];
87
+ const stored = isRecord(globalData) ? globalData[this.globalKey] : undefined;
88
+ if (!Array.isArray(stored))
89
+ return [];
90
+ return stored.filter(isRecord).map((r) => ({
91
+ kind: String(r['kind'] ?? ''),
92
+ about: String(r['about'] ?? ''),
93
+ }));
94
+ }
95
+ /**
96
+ * Note a request to come back to, and tell the model so.
97
+ *
98
+ * The model gets "Noted for right after this: <about>.", with a tool prompt to
99
+ * tell the caller and carry on with what it was doing. The same request noted
100
+ * twice is kept once.
101
+ *
102
+ * @param rawData - The noting call's request.
103
+ * @param kind - The kind of request, one of the app's (it picks the opener).
104
+ * @param about - What it's about, in a few words.
105
+ * @param result - A result to add to.
106
+ * @returns The result.
107
+ */
108
+ note(rawData, kind, about, result) {
109
+ const requests = this.pending(rawData);
110
+ if (!requests.some((r) => r.kind === kind && r.about === about)) {
111
+ requests.push({ kind, about });
112
+ }
113
+ const out = (result ?? new FunctionResult()).setToolResponse(`Noted for right after this: ${about}.`, "Tell the caller you've noted it for right after this, and carry on " +
114
+ 'with what you were doing.');
115
+ return this.store(out, requests);
116
+ }
117
+ /**
118
+ * The oldest request not yet taken up, with its `opener`, or null.
119
+ * @param rawData - The call's request.
120
+ * @returns The request.
121
+ */
122
+ next(rawData) {
123
+ const first = this.pending(rawData)[0];
124
+ return first ? { ...first, opener: this.opener(first) } : null;
125
+ }
126
+ /**
127
+ * Remove the oldest request, once it has been taken up.
128
+ * @param rawData - The call's request.
129
+ * @param result - A result to add to.
130
+ * @returns The result.
131
+ */
132
+ done(rawData, result) {
133
+ return this.store(result ?? new FunctionResult(), this.pending(rawData).slice(1));
134
+ }
135
+ /**
136
+ * How the agent opens a request when it takes it up.
137
+ * @param request - The request.
138
+ * @returns The opener.
139
+ */
140
+ opener(request) {
141
+ const about = String(request.about ?? '');
142
+ const kind = String(request.kind ?? '');
143
+ const template = Object.hasOwn(this.openers, kind) ? this.openers[kind] : undefined;
144
+ return template ? template.replaceAll('{about}', () => about) : about;
145
+ }
146
+ /**
147
+ * The list as step text: the heading and one numbered line a request, or ""
148
+ * when there are none.
149
+ * @param requests - The requests.
150
+ * @returns The text.
151
+ */
152
+ asText(requests) {
153
+ if (requests.length === 0)
154
+ return '';
155
+ return [
156
+ this.heading,
157
+ ...requests.map((r, n) => `${n + 1}. ${this.opener(r)}`),
158
+ "When the current task is done, take these up in order, then ask if there's anything else.",
159
+ ].join('\n');
160
+ }
161
+ store(result, requests) {
162
+ return result.updateGlobalData({
163
+ [this.globalKey]: requests,
164
+ [this.textKey]: this.asText(requests),
165
+ });
166
+ }
167
+ }
168
+ function isRecord(value) {
169
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
170
+ }
171
+ //# sourceMappingURL=RequestList.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"RequestList.js","sourceRoot":"","sources":["../../src/patterns/RequestList.ts"],"names":[],"mappings":"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"}
@@ -4,6 +4,7 @@
4
4
  * Skills are modular capabilities that can be added to an agent.
5
5
  * They define tools, prompt sections, hints, and global data.
6
6
  */
7
+ import type { ToolMiddleware } from '../ToolMiddleware.js';
7
8
  import type { SwaigHandler } from '../SwaigFunction.js';
8
9
  import type { FillerPhrases, SemanticGate } from '../SemanticGate.js';
9
10
  import type { SwaigRequest } from '../SwaigContracts.js';
@@ -54,6 +55,28 @@ export interface SkillToolDefinition {
54
55
  gates?: ReadonlyArray<SemanticGate | Record<string, unknown>>;
55
56
  /** Phrases the AI says while the gates are checked, shaped like `fillers`. */
56
57
  gate_fillers?: FillerPhrases;
58
+ /**
59
+ * Whether the model must vouch that the arguments came from the user (see
60
+ * `SwaigFunctionOptions.vouched`). Wins over the skill's `swaig_fields`.
61
+ */
62
+ vouched?: boolean;
63
+ /**
64
+ * Whether optional arguments take null (see
65
+ * `SwaigFunctionOptions.nullableOptional`). Wins over the skill's
66
+ * `swaig_fields`.
67
+ */
68
+ nullable_optional?: boolean;
69
+ /**
70
+ * Whether the handler reads the conversation (see
71
+ * `SwaigFunctionOptions.needsConversation`). Wins over the skill's
72
+ * `swaig_fields`.
73
+ */
74
+ needs_conversation?: boolean;
75
+ /**
76
+ * Middleware around this tool's calls (see `SwaigFunctionOptions.middleware`).
77
+ * Wins over the skill's `swaig_fields`.
78
+ */
79
+ middleware?: readonly ToolMiddleware[];
57
80
  }
58
81
  /**
59
82
  * Build a {@link SkillToolDefinition} whose `handler` args are *inferred* from
@@ -112,7 +135,7 @@ export interface SkillToolDefinition {
112
135
  export declare function defineSkillTool<const P extends ToolParameters = ToolParameters, const R extends readonly PropertyKey[] = []>(toolDef: Omit<SkillToolDefinition, 'parameters' | 'required' | 'handler'> & {
113
136
  parameters?: P;
114
137
  required?: R;
115
- handler: (args: ToolArgs<P, R>, rawData: SwaigRequest, agent?: AgentBase) => FunctionResult | Record<string, unknown> | string | Promise<FunctionResult | Record<string, unknown> | string>;
138
+ handler: (args: ToolArgs<P, R>, rawData: SwaigRequest, agent?: AgentBase) => FunctionResult | Record<string, unknown> | string | null | undefined | void | Promise<FunctionResult | Record<string, unknown> | string | null | undefined | void>;
116
139
  }): SkillToolDefinition;
117
140
  /** A section of prompt content injected into the agent's system prompt by a skill. */
118
141
  export interface SkillPromptSection {
@@ -337,9 +337,20 @@ export class SkillBase {
337
337
  */
338
338
  defineTool(toolDef) {
339
339
  const swaigDefaults = this.swaigFields;
340
+ // A tool given as SwaigFunctionOptions spells these in camel case; its own
341
+ // value is carried in the snake-case spelling too, so it wins over the
342
+ // skill's default for it
343
+ const own = { ...toolDef };
344
+ for (const [camel, snake] of [
345
+ ['nullableOptional', 'nullable_optional'],
346
+ ['needsConversation', 'needs_conversation'],
347
+ ]) {
348
+ if (own[camel] !== undefined && own[snake] === undefined)
349
+ own[snake] = own[camel];
350
+ }
340
351
  const merged = {
341
352
  ...swaigDefaults,
342
- ...toolDef,
353
+ ...own,
343
354
  };
344
355
  this._dynamicTools.push(merged);
345
356
  }
@@ -1 +1 @@
1
- {"version":3,"file":"SkillBase.js","sourceRoot":"","sources":["../../src/skills/SkillBase.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"SkillBase.js","sourceRoot":"","sources":["../../src/skills/SkillBase.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Numbers as an English text-to-speech voice should say them.
3
+ *
4
+ * The platform normalizes text before its pronunciation rules run, so a bare
5
+ * number is already words by then: `addPronunciation` can't make "10001" read
6
+ * digit by digit. Give the model, or a `say` action, the words instead.
7
+ */
8
+ /**
9
+ * `n` in English words: `numberWords(1405)` is "one thousand four hundred five".
10
+ * @param n - A whole number, as a safe integer or a bigint.
11
+ * @returns The words.
12
+ * @throws Error for a number that isn't whole, or of a quadrillion or more.
13
+ */
14
+ export declare function numberWords(n: number | bigint): string;
15
+ /** Options for {@link sayDigits} and {@link sayLastDigits}. */
16
+ export interface SayDigitsOptions {
17
+ /** The word for 0, such as "oh". Default "zero". */
18
+ zero?: string;
19
+ }
20
+ /**
21
+ * The digits in `text`, one word each, as a voice should read a ZIP code, an
22
+ * account number or a phone number.
23
+ *
24
+ * `sayDigits('415-555-0192')` is "four one five, five five five, zero one nine
25
+ * two": with `group` left out, the groups are the ones the text has, separated
26
+ * by anything that isn't a digit. `group` 3 splits the digits into threes;
27
+ * `[3, 3, 4]` into those sizes, the rest in a last group. A comma between
28
+ * groups makes the voice pause.
29
+ *
30
+ * @param text - The digits, with any separators.
31
+ * @param group - The group size, or the sizes in order.
32
+ * @param opts - `zero`, the word for 0.
33
+ * @returns The words, or "" when `text` has no digits.
34
+ * @throws Error for a group size that isn't a positive whole number.
35
+ */
36
+ export declare function sayDigits(text: string | number | bigint, group?: number | readonly number[] | null, opts?: SayDigitsOptions): string;
37
+ /**
38
+ * The last `n` digits of `text`, one word each: for "a card ending in ..." or
39
+ * "the account ending in ...".
40
+ *
41
+ * `sayLastDigits('4111 1111 1111 1234')` is "one two three four".
42
+ *
43
+ * @param text - The number, with any separators.
44
+ * @param n - How many of its last digits. Default 4.
45
+ * @param opts - `zero`, the word for 0.
46
+ * @returns The words, or "" when `text` has no digits.
47
+ * @throws Error for an `n` that isn't a positive whole number.
48
+ */
49
+ export declare function sayLastDigits(text: string | number | bigint, n?: number, opts?: SayDigitsOptions): string;
50
+ /**
51
+ * An amount of money in words: `sayMoney(14.5)` is "fourteen dollars and fifty
52
+ * cents".
53
+ *
54
+ * The amount is rounded to the currency's smallest unit, half up, from its
55
+ * decimal text, so `sayMoney(0.125)` is "thirteen cents" and `sayMoney('2.675')`
56
+ * "two dollars and sixty-eight cents". The currencies are USD, CAD, AUD, NZD,
57
+ * EUR, GBP, MXN, INR and JPY.
58
+ *
59
+ * @param amount - The amount, in the currency's major unit (dollars, not
60
+ * cents): a number, a bigint, or a decimal string such as "14.50".
61
+ * @param currency - The ISO 4217 code. Default "USD".
62
+ * @returns The words, such as "one dollar", "five cents" or "minus two pounds
63
+ * and one penny".
64
+ * @throws Error for an amount that isn't a finite number, or another currency.
65
+ */
66
+ export declare function sayMoney(amount: number | bigint | string, currency?: string): string;