@signalwire/sdk 2.0.3 → 2.0.5

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/dist/AgentBase.d.ts +72 -40
  2. package/dist/AgentBase.js +147 -85
  3. package/dist/AgentBase.js.map +1 -1
  4. package/dist/POM/PromptObjectModel.d.ts +152 -0
  5. package/dist/POM/PromptObjectModel.js +465 -0
  6. package/dist/POM/PromptObjectModel.js.map +1 -0
  7. package/dist/PomBuilder.d.ts +10 -0
  8. package/dist/PomBuilder.js +28 -0
  9. package/dist/PomBuilder.js.map +1 -1
  10. package/dist/PromptManager.d.ts +7 -0
  11. package/dist/PromptManager.js +9 -0
  12. package/dist/PromptManager.js.map +1 -1
  13. package/dist/SWMLService.d.ts +121 -22
  14. package/dist/SWMLService.js +249 -17
  15. package/dist/SWMLService.js.map +1 -1
  16. package/dist/SecurityUtils.d.ts +7 -0
  17. package/dist/SecurityUtils.js +11 -0
  18. package/dist/SecurityUtils.js.map +1 -1
  19. package/dist/ServerlessAdapter.d.ts +4 -4
  20. package/dist/ServerlessAdapter.js.map +1 -1
  21. package/dist/cli/agent-loader.js +3 -1
  22. package/dist/cli/agent-loader.js.map +1 -1
  23. package/dist/cli/swaig-test.js +7 -3
  24. package/dist/cli/swaig-test.js.map +1 -1
  25. package/dist/index.d.ts +86 -2
  26. package/dist/index.js +107 -1
  27. package/dist/index.js.map +1 -1
  28. package/dist/relay/Call.js +14 -6
  29. package/dist/relay/Call.js.map +1 -1
  30. package/dist/relay/RelayClient.d.ts +38 -0
  31. package/dist/relay/RelayClient.js +101 -3
  32. package/dist/relay/RelayClient.js.map +1 -1
  33. package/dist/relay/normalize.d.ts +27 -0
  34. package/dist/relay/normalize.js +53 -0
  35. package/dist/relay/normalize.js.map +1 -0
  36. package/dist/relay/types.d.ts +11 -0
  37. package/dist/rest/callHandler.d.ts +60 -0
  38. package/dist/rest/callHandler.js +59 -0
  39. package/dist/rest/callHandler.js.map +1 -0
  40. package/dist/rest/index.d.ts +3 -1
  41. package/dist/rest/index.js +3 -1
  42. package/dist/rest/index.js.map +1 -1
  43. package/dist/rest/namespaces/fabric.d.ts +59 -5
  44. package/dist/rest/namespaces/fabric.js +81 -5
  45. package/dist/rest/namespaces/fabric.js.map +1 -1
  46. package/dist/rest/namespaces/phone-numbers.d.ts +141 -1
  47. package/dist/rest/namespaces/phone-numbers.js +169 -1
  48. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  49. package/dist/skills/SkillRegistry.d.ts +29 -0
  50. package/dist/skills/SkillRegistry.js +42 -0
  51. package/dist/skills/SkillRegistry.js.map +1 -1
  52. package/dist/skills/builtin/api_ninjas_trivia.js +6 -2
  53. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  54. package/dist/skills/builtin/datasphere.js +13 -3
  55. package/dist/skills/builtin/datasphere.js.map +1 -1
  56. package/dist/skills/builtin/spider.d.ts +7 -0
  57. package/dist/skills/builtin/spider.js +45 -2
  58. package/dist/skills/builtin/spider.js.map +1 -1
  59. package/dist/skills/builtin/weather_api.js +19 -1
  60. package/dist/skills/builtin/weather_api.js.map +1 -1
  61. package/dist/skills/builtin/web_search.js +28 -5
  62. package/dist/skills/builtin/web_search.js.map +1 -1
  63. package/dist/skills/builtin/wikipedia_search.js +18 -1
  64. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  65. package/dist/types.d.ts +7 -1
  66. package/package.json +5 -2
@@ -6,6 +6,8 @@
6
6
  */
7
7
  import { Hono } from 'hono';
8
8
  import { PromptManager } from './PromptManager.js';
9
+ import { PromptObjectModel } from './POM/PromptObjectModel.js';
10
+ import { SWMLService } from './SWMLService.js';
9
11
  import { SwaigFunction, type SwaigHandler } from './SwaigFunction.js';
10
12
  import { ContextBuilder } from './ContextBuilder.js';
11
13
  import { SkillManager } from './skills/SkillManager.js';
@@ -82,21 +84,11 @@ export type RoutingCallback = (body: Record<string, unknown>) => string | null |
82
84
  * @see {@link DataMap} — server-side tools without webhooks
83
85
  * @see {@link AgentServer} — host multiple agents on one HTTP server
84
86
  */
85
- export declare class AgentBase {
86
- /** Display name of this agent. */
87
- name: string;
88
- /** HTTP route path this agent listens on. */
89
- route: string;
90
- /** Hostname the HTTP server binds to. */
91
- host: string;
92
- /** Port number the HTTP server listens on. */
93
- port: number;
87
+ export declare class AgentBase extends SWMLService {
94
88
  /** Unique identifier for this agent instance. */
95
89
  agentId: string;
96
90
  private _promptManager;
97
91
  private sessionManager;
98
- private swmlBuilder;
99
- private toolRegistry;
100
92
  private basicAuthCreds;
101
93
  private basicAuthSource;
102
94
  private autoAnswer;
@@ -131,12 +123,11 @@ export declare class AgentBase {
131
123
  private _sipUsernames;
132
124
  private debugEventsEnabled;
133
125
  private debugEventsLevel;
134
- private _proxyUrlBase;
135
- private _proxyUrlBaseFromEnv;
136
126
  private _proxyDebug;
137
127
  private _trustProxyHeaders;
138
128
  private _enforceHttps;
139
- /** Structured logger instance for this agent, configurable via SIGNALWIRE_LOG_LEVEL. */
129
+ /** Structured logger instance for this agent. Override the inherited
130
+ * SWMLService logger with an AgentBase-tagged one. */
140
131
  log: import("./Logger.js").Logger;
141
132
  private _skillManager;
142
133
  private _enablePostPromptOverride;
@@ -144,8 +135,7 @@ export declare class AgentBase {
144
135
  private _schemaValidation;
145
136
  private _configFile;
146
137
  private _schemaPath;
147
- private _routingCallbacks;
148
- private _app;
138
+ private _appBuiltByAgent;
149
139
  /**
150
140
  * Create a new AgentBase instance.
151
141
  * @param opts - Agent configuration options including name, route, auth, and call settings.
@@ -183,6 +173,24 @@ export declare class AgentBase {
183
173
  * provides equivalent access for direct POM manipulation.
184
174
  */
185
175
  get promptManager(): PromptManager;
176
+ /**
177
+ * Public accessor for the agent's POM as a {@link PromptObjectModel} instance.
178
+ *
179
+ * Python parity: ``agent.pom`` instance attribute (agent_base.py line 209)
180
+ * is a ``signalwire.pom.pom.PromptObjectModel`` when ``use_pom=True``,
181
+ * or ``None`` otherwise. This getter returns the equivalent TypeScript
182
+ * ``PromptObjectModel`` instance — callers can use ``addSection``,
183
+ * ``findSection``, ``renderMarkdown``, ``renderXml``, ``toJson``, ``toYaml``
184
+ * exactly as in Python.
185
+ *
186
+ * The instance returned is a fresh snapshot built from the current
187
+ * ``PomBuilder`` state, so mutating it does not feed back into the agent's
188
+ * internal builder. To mutate the agent's prompt, use
189
+ * ``promptAddSection`` / ``promptAddToSection`` / ``promptAddSubsection``.
190
+ *
191
+ * @returns A `PromptObjectModel` populated with the agent's sections, or `null` when POM mode is off.
192
+ */
193
+ get pom(): PromptObjectModel | null;
186
194
  /**
187
195
  * Public accessor for the native functions list.
188
196
  *
@@ -279,6 +287,17 @@ export declare class AgentBase {
279
287
  * @returns The post-prompt string, or null if not configured.
280
288
  */
281
289
  getPostPrompt(): string | null;
290
+ /**
291
+ * Get the raw prompt text whatever `setPromptText` stored, or null when
292
+ * no raw prompt has been set.
293
+ *
294
+ * Matches Python `PromptManager.get_raw_prompt()` which returns the raw
295
+ * stored string or `None`. Use this instead of `getPrompt()` when you
296
+ * need the unrendered text rather than the POM-rendered Markdown.
297
+ *
298
+ * @returns The raw prompt string, or null if not set.
299
+ */
300
+ getRawPrompt(): string | null;
282
301
  /**
283
302
  * Set the prompt as a POM (Prompt Object Model) dictionary.
284
303
  *
@@ -307,6 +326,16 @@ export declare class AgentBase {
307
326
  * @returns This agent instance for chaining.
308
327
  */
309
328
  resetContexts(): this;
329
+ /**
330
+ * Get the contexts dictionary as serialised SWML, or null when no
331
+ * contexts have been defined yet.
332
+ *
333
+ * Matches Python `PromptManager.get_contexts()` which returns the
334
+ * contexts dict or `None`.
335
+ *
336
+ * @returns Contexts dict, or null when no contexts are defined.
337
+ */
338
+ getContexts(): Record<string, unknown> | null;
310
339
  /**
311
340
  * Add a single speech-recognition hint.
312
341
  * @param hint - Word or phrase to boost in speech recognition.
@@ -660,27 +689,6 @@ export declare class AgentBase {
660
689
  waitFileLoops?: number;
661
690
  required?: string[];
662
691
  }): this;
663
- /**
664
- * Get a summary of all registered tools with their names, descriptions, and parameter schemas.
665
- * @returns Array of tool descriptors.
666
- */
667
- getRegisteredTools(): {
668
- name: string;
669
- description: string;
670
- parameters: Record<string, unknown>;
671
- }[];
672
- /**
673
- * Look up a registered SwaigFunction by name.
674
- * @param name - The tool name to search for.
675
- * @returns The SwaigFunction instance, or undefined if not found or not a SwaigFunction.
676
- */
677
- getTool(name: string): SwaigFunction | undefined;
678
- /**
679
- * Register a pre-built SwaigFunction instance or a raw function descriptor (e.g. DataMap).
680
- * @param fn - A SwaigFunction instance or a plain object with a "function" key.
681
- * @returns This agent instance for chaining.
682
- */
683
- registerSwaigFunction(fn: SwaigFunction | Record<string, unknown>): this;
684
692
  /**
685
693
  * Validate a tool-call token for the given function.
686
694
  *
@@ -704,13 +712,21 @@ export declare class AgentBase {
704
712
  * unchanged and the underlying validator will reject it.
705
713
  */
706
714
  validateToolToken(functionName: string, token: string, callId: string): boolean;
715
+ /**
716
+ * Mint a per-call SWAIG-function token via the agent's SessionManager.
717
+ *
718
+ * Mirrors Python reference `core/mixins/state_mixin.py _create_tool_token`:
719
+ * delegates to `SessionManager.createToolToken` and returns an empty
720
+ * string on any failure (Python catches all exceptions and returns "").
721
+ */
722
+ createToolToken(toolName: string, callId: string): string;
707
723
  /**
708
724
  * Add a SWML verb to execute before the answer phase (phase 1).
709
725
  * @param verbName - Name of the SWML verb (e.g. "play", "record").
710
726
  * @param config - Verb configuration object.
711
727
  * @returns This agent instance for chaining.
712
728
  */
713
- addPreAnswerVerb(verbName: string, config: Record<string, unknown>): this;
729
+ addPreAnswerVerb(verbName: string, config: Record<string, unknown> | number): this;
714
730
  /**
715
731
  * Configure the answer verb (phase 2) with optional settings.
716
732
  * @param config - Optional answer verb configuration.
@@ -723,7 +739,7 @@ export declare class AgentBase {
723
739
  * @param config - Verb configuration object.
724
740
  * @returns This agent instance for chaining.
725
741
  */
726
- addPostAnswerVerb(verbName: string, config: Record<string, unknown>): this;
742
+ addPostAnswerVerb(verbName: string, config: Record<string, unknown> | number): this;
727
743
  /**
728
744
  * Add a SWML verb to execute after the AI verb (phase 5).
729
745
  * @param verbName - Name of the SWML verb.
@@ -903,6 +919,22 @@ export declare class AgentBase {
903
919
  * ```
904
920
  */
905
921
  onSummary(_summary: Record<string, unknown> | null, _rawData: Record<string, unknown>): void | Promise<void>;
922
+ /**
923
+ * Lifecycle hook called when SWML is requested. Default delegates to
924
+ * {@link onSwmlRequest} and returns its result. Subclasses typically
925
+ * override `onSwmlRequest` rather than this method.
926
+ *
927
+ * Matches Python `WebMixin.on_request(request_data, callback_path)`. The
928
+ * cross-language API is the two-arg form; the Hono `context` argument is
929
+ * a TypeScript-side extra preserved for callers that already have it but
930
+ * is not part of the audited surface.
931
+ *
932
+ * @param requestData - The parsed request body.
933
+ * @param callbackPath - Optional callback path from the request.
934
+ * @returns Optionally a dict of SWML modifications, or undefined for
935
+ * default rendering.
936
+ */
937
+ onRequest(requestData?: Record<string, unknown> | null, callbackPath?: string | null): Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
906
938
  /**
907
939
  * Lifecycle hook called on every SWML request before rendering. Override in subclasses.
908
940
  *
@@ -1041,5 +1073,5 @@ export declare class AgentBase {
1041
1073
  * @returns A tuple of [username, password] or [username, password, source].
1042
1074
  */
1043
1075
  getBasicAuthCredentials(includeSource?: false): [string, string];
1044
- getBasicAuthCredentials(includeSource: true): [string, string, 'provided' | 'environment' | 'auto-generated'];
1076
+ getBasicAuthCredentials(includeSource: true): [string, string, 'provided' | 'environment' | 'generated'];
1045
1077
  }
package/dist/AgentBase.js CHANGED
@@ -11,6 +11,7 @@ import { randomBytes } from 'node:crypto';
11
11
  import { PromptManager } from './PromptManager.js';
12
12
  import { SessionManager } from './SessionManager.js';
13
13
  import { SwmlBuilder } from './SwmlBuilder.js';
14
+ import { SWMLService } from './SWMLService.js';
14
15
  import { ConfigLoader } from './ConfigLoader.js';
15
16
  import { SwaigFunction } from './SwaigFunction.js';
16
17
  import { inferSchema, createTypedHandlerWrapper } from './TypeInference.js';
@@ -82,25 +83,19 @@ import { ServerlessAdapter } from './ServerlessAdapter.js';
82
83
  * @see {@link DataMap} — server-side tools without webhooks
83
84
  * @see {@link AgentServer} — host multiple agents on one HTTP server
84
85
  */
85
- export class AgentBase {
86
- /** Display name of this agent. */
87
- name;
88
- /** HTTP route path this agent listens on. */
89
- route;
90
- /** Hostname the HTTP server binds to. */
91
- host;
92
- /** Port number the HTTP server listens on. */
93
- port;
86
+ export class AgentBase extends SWMLService {
87
+ // name, route, host, port, swmlBuilder, _app, authCredentials, toolRegistry
88
+ // are inherited from SWMLService. Agent-specific state below only.
94
89
  /** Unique identifier for this agent instance. */
95
90
  agentId;
96
91
  // Internal managers
97
92
  _promptManager;
98
93
  sessionManager;
99
- swmlBuilder;
100
- toolRegistry = new Map();
101
- // Auth
94
+ // Auth — mirrors of inherited authCredentials kept for legacy callers that
95
+ // read basicAuthCreds directly. The Hono basicAuth middleware uses the
96
+ // inherited credentials (set in super()).
102
97
  basicAuthCreds;
103
- basicAuthSource = 'auto-generated';
98
+ basicAuthSource = 'generated';
104
99
  // Call settings
105
100
  autoAnswer;
106
101
  _recordCall;
@@ -142,13 +137,13 @@ export class AgentBase {
142
137
  // Debug
143
138
  debugEventsEnabled = false;
144
139
  debugEventsLevel = 1;
145
- // Proxy detection
146
- _proxyUrlBase = process.env['SWML_PROXY_URL_BASE'] ?? null;
147
- _proxyUrlBaseFromEnv = !!process.env['SWML_PROXY_URL_BASE'];
140
+ // Proxy detection — _proxyUrlBase and _proxyUrlBaseFromEnv inherited from
141
+ // SWMLService.
148
142
  _proxyDebug = process.env['SWML_PROXY_DEBUG'] === 'true';
149
143
  _trustProxyHeaders = process.env['SWML_TRUST_PROXY_HEADERS'] === 'true';
150
144
  _enforceHttps = process.env['SWML_ENFORCE_HTTPS'] === 'true';
151
- /** Structured logger instance for this agent, configurable via SIGNALWIRE_LOG_LEVEL. */
145
+ /** Structured logger instance for this agent. Override the inherited
146
+ * SWMLService logger with an AgentBase-tagged one. */
152
147
  log = getLogger('AgentBase');
153
148
  // Skills
154
149
  _skillManager = new SkillManager();
@@ -158,19 +153,24 @@ export class AgentBase {
158
153
  _schemaValidation = true;
159
154
  _configFile = null;
160
155
  _schemaPath = null;
161
- // Routing callbacks (registered via registerRoutingCallback)
162
- _routingCallbacks = new Map();
163
- // Hono app
164
- _app = null;
156
+ // _routingCallbacks and _app are inherited from SWMLService.
157
+ // AgentBase rebuilds _app in getApp() with its own middleware stack and
158
+ // route handlers, overwriting the parent-init Hono instance. The flag
159
+ // below tracks whether AgentBase's own setup has run; the parent-init
160
+ // Hono is replaced on first AgentBase getApp() call.
161
+ _appBuiltByAgent = false;
165
162
  /**
166
163
  * Create a new AgentBase instance.
167
164
  * @param opts - Agent configuration options including name, route, auth, and call settings.
168
165
  */
169
166
  constructor(opts) {
170
- // Load config file if provided — values are defaults, constructor args take precedence
167
+ // Resolve construction-time config (config file + opts) before super(),
168
+ // because TypeScript's strict superclass-call rules require all `this`-
169
+ // touching code to come after super(). Forward the resolved values into
170
+ // SWMLService via super() so name/route/host/port/auth are set on the
171
+ // single source of truth in the parent.
171
172
  let serviceConfig = {};
172
173
  if (opts.configFile) {
173
- this._configFile = opts.configFile;
174
174
  try {
175
175
  const loader = new ConfigLoader(opts.configFile);
176
176
  serviceConfig = (loader.get('service') ?? {});
@@ -179,19 +179,31 @@ export class AgentBase {
179
179
  // Config file not found or invalid — continue with constructor args
180
180
  }
181
181
  }
182
- // Config file values: constructor args take precedence unless at default values
183
- // (matching Python's behavior where non-default constructor args always win)
184
- this.name = serviceConfig['name'] ?? opts.name;
182
+ const resolvedName = serviceConfig['name'] ?? opts.name;
185
183
  const routeArg = opts.route ?? '/';
186
- this.route = (routeArg !== '/' ? routeArg : (serviceConfig['route'] ?? routeArg)).replace(/\/+$/, '') || '/';
184
+ const resolvedRoute = (routeArg !== '/'
185
+ ? routeArg
186
+ : (serviceConfig['route'] ?? routeArg)).replace(/\/+$/, '') || '/';
187
187
  const hostArg = opts.host ?? '0.0.0.0';
188
- this.host = hostArg !== '0.0.0.0' ? hostArg : (serviceConfig['host'] ?? hostArg);
188
+ const resolvedHost = hostArg !== '0.0.0.0' ? hostArg : (serviceConfig['host'] ?? hostArg);
189
189
  const configPort = serviceConfig['port'];
190
190
  const parsedPort = opts.port ?? configPort ?? parseInt(process.env['PORT'] ?? '3000', 10);
191
191
  if (isNaN(parsedPort) || parsedPort < 1 || parsedPort > 65535) {
192
192
  throw new Error(`Invalid port: ${opts.port ?? process.env['PORT']}. Must be between 1 and 65535.`);
193
193
  }
194
- this.port = parsedPort;
194
+ super({
195
+ name: resolvedName,
196
+ route: resolvedRoute,
197
+ host: resolvedHost,
198
+ port: parsedPort,
199
+ ...(opts.basicAuth ? { basicAuth: opts.basicAuth } : {}),
200
+ ...(opts.configFile ? { configFile: opts.configFile } : {}),
201
+ ...(opts.schemaPath ? { schemaPath: opts.schemaPath } : {}),
202
+ schemaValidation: opts.schemaValidation ?? true,
203
+ });
204
+ if (opts.configFile) {
205
+ this._configFile = opts.configFile;
206
+ }
195
207
  this.agentId = opts.agentId ?? randomBytes(8).toString('hex');
196
208
  this.autoAnswer = opts.autoAnswer ?? true;
197
209
  this._recordCall = opts.recordCall ?? false;
@@ -209,13 +221,11 @@ export class AgentBase {
209
221
  }
210
222
  this._promptManager = new PromptManager(opts.usePom ?? true);
211
223
  this.sessionManager = new SessionManager(opts.tokenExpirySecs ?? 3600);
212
- // Forward schemaValidation + schemaPath into SwmlBuilder.
213
- // Python equivalent: SchemaUtils(schema_path, schema_validation=...) inside SWMLService.
214
- this.swmlBuilder = new SwmlBuilder({
215
- enableValidation: this._schemaValidation,
216
- ...(this._schemaPath ? { schemaPath: this._schemaPath } : {}),
217
- });
218
- // Setup auth
224
+ // swmlBuilder is inherited from SWMLService (initialized via super()).
225
+ // Setup auth — populate the legacy basicAuthCreds/basicAuthSource
226
+ // mirrors so AgentBase callers that read them still work.
227
+ // SWMLService's authCredentials (set in super()) is the source of truth
228
+ // for HTTP-level enforcement.
219
229
  if (opts.basicAuth) {
220
230
  this.basicAuthCreds = opts.basicAuth;
221
231
  this.basicAuthSource = 'provided';
@@ -235,7 +245,7 @@ export class AgentBase {
235
245
  // getting HTTP 401.
236
246
  const username = envUser || this.name;
237
247
  this.basicAuthCreds = [username, randomBytes(16).toString('hex')];
238
- this.basicAuthSource = 'auto-generated';
248
+ this.basicAuthSource = 'generated';
239
249
  this.log.warn(`basic_auth_password_autogenerated: username="${username}". ` +
240
250
  `No SWML_BASIC_AUTH_PASSWORD found in environment and no basicAuth ` +
241
251
  `passed to the agent constructor. The SDK generated a random ` +
@@ -293,6 +303,29 @@ export class AgentBase {
293
303
  get promptManager() {
294
304
  return this._promptManager;
295
305
  }
306
+ /**
307
+ * Public accessor for the agent's POM as a {@link PromptObjectModel} instance.
308
+ *
309
+ * Python parity: ``agent.pom`` instance attribute (agent_base.py line 209)
310
+ * is a ``signalwire.pom.pom.PromptObjectModel`` when ``use_pom=True``,
311
+ * or ``None`` otherwise. This getter returns the equivalent TypeScript
312
+ * ``PromptObjectModel`` instance — callers can use ``addSection``,
313
+ * ``findSection``, ``renderMarkdown``, ``renderXml``, ``toJson``, ``toYaml``
314
+ * exactly as in Python.
315
+ *
316
+ * The instance returned is a fresh snapshot built from the current
317
+ * ``PomBuilder`` state, so mutating it does not feed back into the agent's
318
+ * internal builder. To mutate the agent's prompt, use
319
+ * ``promptAddSection`` / ``promptAddToSection`` / ``promptAddSubsection``.
320
+ *
321
+ * @returns A `PromptObjectModel` populated with the agent's sections, or `null` when POM mode is off.
322
+ */
323
+ get pom() {
324
+ const builder = this._promptManager.getPomBuilder();
325
+ if (!builder)
326
+ return null;
327
+ return builder.pom;
328
+ }
296
329
  /**
297
330
  * Public accessor for the native functions list.
298
331
  *
@@ -408,6 +441,19 @@ export class AgentBase {
408
441
  getPostPrompt() {
409
442
  return this._promptManager.getPostPrompt();
410
443
  }
444
+ /**
445
+ * Get the raw prompt text whatever `setPromptText` stored, or null when
446
+ * no raw prompt has been set.
447
+ *
448
+ * Matches Python `PromptManager.get_raw_prompt()` which returns the raw
449
+ * stored string or `None`. Use this instead of `getPrompt()` when you
450
+ * need the unrendered text rather than the POM-rendered Markdown.
451
+ *
452
+ * @returns The raw prompt string, or null if not set.
453
+ */
454
+ getRawPrompt() {
455
+ return this._promptManager.getRawPrompt();
456
+ }
411
457
  /**
412
458
  * Set the prompt as a POM (Prompt Object Model) dictionary.
413
459
  *
@@ -471,6 +517,20 @@ export class AgentBase {
471
517
  }
472
518
  return this;
473
519
  }
520
+ /**
521
+ * Get the contexts dictionary as serialised SWML, or null when no
522
+ * contexts have been defined yet.
523
+ *
524
+ * Matches Python `PromptManager.get_contexts()` which returns the
525
+ * contexts dict or `None`.
526
+ *
527
+ * @returns Contexts dict, or null when no contexts are defined.
528
+ */
529
+ getContexts() {
530
+ if (!this.contextsBuilder)
531
+ return null;
532
+ return this.contextsBuilder.toDict();
533
+ }
474
534
  // ── AI config methods ───────────────────────────────────────────────
475
535
  /**
476
536
  * Add a single speech-recognition hint.
@@ -856,8 +916,10 @@ export class AgentBase {
856
916
  if (!normalized.startsWith('/'))
857
917
  normalized = `/${normalized}`;
858
918
  this._routingCallbacks.set(normalized, callback);
859
- // Invalidate cached app so getApp() re-registers routes with the new callback
860
- this._app = null;
919
+ // Invalidate cached app so getApp() re-registers routes with the new callback.
920
+ // _app is non-nullable on the parent (SWMLService); rebuild fresh.
921
+ this._app = new Hono();
922
+ this._appBuiltByAgent = false;
861
923
  return this;
862
924
  }
863
925
  /**
@@ -1126,50 +1188,9 @@ export class AgentBase {
1126
1188
  this.toolRegistry.set(opts.name, fn);
1127
1189
  return this;
1128
1190
  }
1129
- /**
1130
- * Get a summary of all registered tools with their names, descriptions, and parameter schemas.
1131
- * @returns Array of tool descriptors.
1132
- */
1133
- getRegisteredTools() {
1134
- const tools = [];
1135
- for (const [name, fn] of this.toolRegistry) {
1136
- if (fn instanceof SwaigFunction) {
1137
- tools.push({ name, description: fn.description, parameters: fn.parameters });
1138
- }
1139
- else {
1140
- tools.push({
1141
- name,
1142
- description: fn['purpose'] ?? '',
1143
- parameters: fn['argument'] ?? {},
1144
- });
1145
- }
1146
- }
1147
- return tools;
1148
- }
1149
- /**
1150
- * Look up a registered SwaigFunction by name.
1151
- * @param name - The tool name to search for.
1152
- * @returns The SwaigFunction instance, or undefined if not found or not a SwaigFunction.
1153
- */
1154
- getTool(name) {
1155
- const fn = this.toolRegistry.get(name);
1156
- return fn instanceof SwaigFunction ? fn : undefined;
1157
- }
1158
- /**
1159
- * Register a pre-built SwaigFunction instance or a raw function descriptor (e.g. DataMap).
1160
- * @param fn - A SwaigFunction instance or a plain object with a "function" key.
1161
- * @returns This agent instance for chaining.
1162
- */
1163
- registerSwaigFunction(fn) {
1164
- if (fn instanceof SwaigFunction) {
1165
- this.toolRegistry.set(fn.name, fn);
1166
- }
1167
- else {
1168
- const name = fn['function'];
1169
- this.toolRegistry.set(name, fn);
1170
- }
1171
- return this;
1172
- }
1191
+ // getRegisteredTools / getTool / registerSwaigFunction are inherited from
1192
+ // SWMLService (the toolRegistry was lifted there so non-AgentBase services
1193
+ // — sidecars, standalone SWAIG hosts — can use the same surface).
1173
1194
  /**
1174
1195
  * Validate a tool-call token for the given function.
1175
1196
  *
@@ -1201,7 +1222,27 @@ export class AgentBase {
1201
1222
  return true;
1202
1223
  if (!token)
1203
1224
  return false;
1204
- return this.sessionManager.validateToolToken(functionName, token, callId);
1225
+ try {
1226
+ return this.sessionManager.validateToolToken(functionName, token, callId);
1227
+ }
1228
+ catch {
1229
+ return false;
1230
+ }
1231
+ }
1232
+ /**
1233
+ * Mint a per-call SWAIG-function token via the agent's SessionManager.
1234
+ *
1235
+ * Mirrors Python reference `core/mixins/state_mixin.py _create_tool_token`:
1236
+ * delegates to `SessionManager.createToolToken` and returns an empty
1237
+ * string on any failure (Python catches all exceptions and returns "").
1238
+ */
1239
+ createToolToken(toolName, callId) {
1240
+ try {
1241
+ return this.sessionManager.createToolToken(toolName, callId);
1242
+ }
1243
+ catch {
1244
+ return '';
1245
+ }
1205
1246
  }
1206
1247
  // ── Call flow ───────────────────────────────────────────────────────
1207
1248
  /**
@@ -1598,6 +1639,24 @@ export class AgentBase {
1598
1639
  onSummary(_summary, _rawData) {
1599
1640
  // Default no-op
1600
1641
  }
1642
+ /**
1643
+ * Lifecycle hook called when SWML is requested. Default delegates to
1644
+ * {@link onSwmlRequest} and returns its result. Subclasses typically
1645
+ * override `onSwmlRequest` rather than this method.
1646
+ *
1647
+ * Matches Python `WebMixin.on_request(request_data, callback_path)`. The
1648
+ * cross-language API is the two-arg form; the Hono `context` argument is
1649
+ * a TypeScript-side extra preserved for callers that already have it but
1650
+ * is not part of the audited surface.
1651
+ *
1652
+ * @param requestData - The parsed request body.
1653
+ * @param callbackPath - Optional callback path from the request.
1654
+ * @returns Optionally a dict of SWML modifications, or undefined for
1655
+ * default rendering.
1656
+ */
1657
+ onRequest(requestData, callbackPath) {
1658
+ return this.onSwmlRequest(requestData ?? {}, callbackPath ?? undefined);
1659
+ }
1601
1660
  /**
1602
1661
  * Lifecycle hook called on every SWML request before rendering. Override in subclasses.
1603
1662
  *
@@ -1915,7 +1974,9 @@ export class AgentBase {
1915
1974
  * @returns The configured Hono application instance.
1916
1975
  */
1917
1976
  getApp() {
1918
- if (this._app)
1977
+ // Service's constructor eagerly initialised _app; AgentBase rebuilds it
1978
+ // here with its own middleware stack and route handlers on first call.
1979
+ if (this._appBuiltByAgent)
1919
1980
  return this._app;
1920
1981
  const app = new Hono();
1921
1982
  // Security headers
@@ -2239,6 +2300,7 @@ export class AgentBase {
2239
2300
  app.get(`${basePath}/health`, (c) => c.json({ status: 'ok' }));
2240
2301
  app.get(`${basePath}/ready`, (c) => c.json({ status: 'ready' }));
2241
2302
  this._app = app;
2303
+ this._appBuiltByAgent = true;
2242
2304
  return app;
2243
2305
  }
2244
2306
  /**