@signalwire/sdk 2.0.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.
- package/.github/workflows/publish.yml +27 -0
- package/.github/workflows/test.yml +17 -0
- package/CLAUDE.md +112 -0
- package/README.md +254 -0
- package/docs/MIGRATION-2.0.md +81 -0
- package/docs/agent-guide.md +869 -0
- package/docs/agent_guide.md +1026 -0
- package/docs/api-reference.md +2420 -0
- package/docs/api_reference.md +1301 -0
- package/docs/architecture.md +843 -0
- package/docs/cli-guide.md +579 -0
- package/docs/cli_guide.md +448 -0
- package/docs/cloud_functions_guide.md +474 -0
- package/docs/configuration.md +422 -0
- package/docs/contexts-guide.md +787 -0
- package/docs/contexts_guide.md +511 -0
- package/docs/datamap-guide.md +1141 -0
- package/docs/datamap_guide.md +595 -0
- package/docs/llm_parameters.md +239 -0
- package/docs/mcp_gateway_reference.md +648 -0
- package/docs/mcp_integration.md +108 -0
- package/docs/prefabs-guide.md +800 -0
- package/docs/sdk_features.md +477 -0
- package/docs/security.md +436 -0
- package/docs/serverless-guide.md +513 -0
- package/docs/skills-guide.md +857 -0
- package/docs/skills-system.md +301 -0
- package/docs/skills_parameter_schema.md +392 -0
- package/docs/skills_system.md +467 -0
- package/docs/swaig-reference.md +1627 -0
- package/docs/swaig_reference.md +910 -0
- package/docs/swml_service_guide.md +600 -0
- package/docs/third_party_skills.md +533 -0
- package/docs/web_service.md +677 -0
- package/examples/README.md +131 -0
- package/examples/advanced-datamap.ts +100 -0
- package/examples/advanced-dynamic-config.ts +70 -0
- package/examples/auto-vivified.ts +94 -0
- package/examples/call-flow.ts +63 -0
- package/examples/comprehensive-dynamic.ts +125 -0
- package/examples/contexts-steps.ts +65 -0
- package/examples/custom-path.ts +45 -0
- package/examples/datamap-tools.ts +55 -0
- package/examples/datasphere-multi-instance.ts +63 -0
- package/examples/datasphere-serverless-env.ts +68 -0
- package/examples/datasphere-webhook-env.ts +66 -0
- package/examples/datasphere.ts +37 -0
- package/examples/declarative.ts +100 -0
- package/examples/dynamic-config.ts +54 -0
- package/examples/dynamic-info-gatherer.ts +69 -0
- package/examples/dynamic-swml-service.ts +67 -0
- package/examples/gather-info.ts +71 -0
- package/examples/gather-per-question-functions-demo.ts +140 -0
- package/examples/joke-agent.ts +34 -0
- package/examples/kubernetes-agent.ts +45 -0
- package/examples/llm-params.ts +69 -0
- package/examples/mcp-agent.ts +84 -0
- package/examples/mcp-gateway.ts +35 -0
- package/examples/multi-agent.ts +73 -0
- package/examples/multi-endpoint.ts +79 -0
- package/examples/pom-prompt.ts +71 -0
- package/examples/prefab-concierge.ts +47 -0
- package/examples/prefab-faq.ts +54 -0
- package/examples/prefab-info-gatherer.ts +33 -0
- package/examples/prefab-receptionist.ts +36 -0
- package/examples/prefab-survey.ts +68 -0
- package/examples/record-call.ts +67 -0
- package/examples/relay-demo.ts +33 -0
- package/examples/room-and-sip.ts +94 -0
- package/examples/serverless-lambda.ts +35 -0
- package/examples/session-state.ts +83 -0
- package/examples/simple-agent.ts +36 -0
- package/examples/simple-static.ts +29 -0
- package/examples/skills-demo.ts +38 -0
- package/examples/step-function-inheritance-demo.ts +124 -0
- package/examples/swaig-features.ts +187 -0
- package/examples/swml-service-routing.ts +66 -0
- package/examples/swml-service.ts +38 -0
- package/examples/tap.ts +68 -0
- package/examples/verb-methods.ts +45 -0
- package/examples/web-search-multi-instance.ts +72 -0
- package/examples/web-search.ts +38 -0
- package/examples/wikipedia.ts +36 -0
- package/livewire/README.md +140 -0
- package/livewire/docs/migration-guide.md +228 -0
- package/livewire/examples/livewire-basic-agent.ts +74 -0
- package/livewire/examples/livewire-handoff.ts +197 -0
- package/livewire/examples/livewire-multi-tool.ts +117 -0
- package/package.json +38 -0
- package/relay/README.md +70 -0
- package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
- package/relay/docs/call-methods.md +474 -0
- package/relay/docs/client-reference.md +142 -0
- package/relay/docs/events.md +134 -0
- package/relay/docs/getting-started.md +134 -0
- package/relay/docs/guide.md +306 -0
- package/relay/docs/messaging.md +182 -0
- package/relay/examples/relay-inbound.ts +66 -0
- package/relay/examples/relay-messaging.ts +71 -0
- package/relay/examples/relay-outbound.ts +76 -0
- package/rest/README.md +95 -0
- package/rest/docs/calling.md +273 -0
- package/rest/docs/client-reference.md +107 -0
- package/rest/docs/compat.md +204 -0
- package/rest/docs/fabric.md +183 -0
- package/rest/docs/getting-started.md +110 -0
- package/rest/docs/guide.md +351 -0
- package/rest/docs/namespaces.md +285 -0
- package/rest/examples/rest-10dlc-registration.ts +161 -0
- package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
- package/rest/examples/rest-calling-play-and-record.ts +91 -0
- package/rest/examples/rest-client.ts +65 -0
- package/rest/examples/rest-compat-laml.ts +210 -0
- package/rest/examples/rest-datasphere-search.ts +82 -0
- package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
- package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
- package/rest/examples/rest-manage-resources.ts +65 -0
- package/rest/examples/rest-phone-number-management.ts +197 -0
- package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
- package/rest/examples/rest-video-rooms.ts +186 -0
- package/src/AgentBase.ts +2489 -0
- package/src/AgentServer.ts +415 -0
- package/src/AuthHandler.ts +256 -0
- package/src/ConfigLoader.ts +447 -0
- package/src/ContextBuilder.ts +1150 -0
- package/src/DataMap.ts +449 -0
- package/src/FunctionResult.ts +866 -0
- package/src/Logger.ts +337 -0
- package/src/PomBuilder.ts +439 -0
- package/src/PromptManager.ts +133 -0
- package/src/SWMLHandler.ts +298 -0
- package/src/SWMLService.ts +717 -0
- package/src/SchemaUtils.ts +361 -0
- package/src/SecurityUtils.ts +153 -0
- package/src/ServerlessAdapter.ts +221 -0
- package/src/SessionManager.ts +311 -0
- package/src/SslConfig.ts +118 -0
- package/src/SwaigFunction.ts +276 -0
- package/src/SwmlBuilder.ts +258 -0
- package/src/SwmlVerbMethods.generated.ts +234 -0
- package/src/TypeInference.ts +181 -0
- package/src/WebService.ts +619 -0
- package/src/cli/agent-loader.ts +166 -0
- package/src/cli/mock-data.ts +111 -0
- package/src/cli/swaig-test.ts +452 -0
- package/src/generateVerbTypes.ts +322 -0
- package/src/index.ts +167 -0
- package/src/livewire/index.ts +950 -0
- package/src/prefabs/ConciergeAgent.ts +287 -0
- package/src/prefabs/FAQBotAgent.ts +384 -0
- package/src/prefabs/InfoGathererAgent.ts +339 -0
- package/src/prefabs/ReceptionistAgent.ts +366 -0
- package/src/prefabs/SurveyAgent.ts +646 -0
- package/src/prefabs/index.ts +27 -0
- package/src/relay/Action.ts +314 -0
- package/src/relay/Call.ts +854 -0
- package/src/relay/Deferred.ts +71 -0
- package/src/relay/Message.ts +148 -0
- package/src/relay/RelayClient.ts +1036 -0
- package/src/relay/RelayError.ts +14 -0
- package/src/relay/RelayEvent.ts +892 -0
- package/src/relay/constants.ts +132 -0
- package/src/relay/index.ts +123 -0
- package/src/relay/types.ts +149 -0
- package/src/rest/HttpClient.ts +103 -0
- package/src/rest/RestError.ts +31 -0
- package/src/rest/base/BaseResource.ts +19 -0
- package/src/rest/base/CrudResource.ts +51 -0
- package/src/rest/base/CrudWithAddresses.ts +26 -0
- package/src/rest/index.ts +200 -0
- package/src/rest/namespaces/addresses.ts +32 -0
- package/src/rest/namespaces/calling.ts +187 -0
- package/src/rest/namespaces/chat.ts +20 -0
- package/src/rest/namespaces/compat.ts +352 -0
- package/src/rest/namespaces/datasphere.ts +45 -0
- package/src/rest/namespaces/fabric.ts +222 -0
- package/src/rest/namespaces/imported-numbers.ts +20 -0
- package/src/rest/namespaces/logs.ts +84 -0
- package/src/rest/namespaces/lookup.ts +21 -0
- package/src/rest/namespaces/mfa.ts +30 -0
- package/src/rest/namespaces/number-groups.ts +38 -0
- package/src/rest/namespaces/phone-numbers.ts +44 -0
- package/src/rest/namespaces/project.ts +36 -0
- package/src/rest/namespaces/pubsub.ts +20 -0
- package/src/rest/namespaces/queues.ts +33 -0
- package/src/rest/namespaces/recordings.ts +28 -0
- package/src/rest/namespaces/registry.ts +101 -0
- package/src/rest/namespaces/short-codes.ts +28 -0
- package/src/rest/namespaces/sip-profile.ts +25 -0
- package/src/rest/namespaces/verified-callers.ts +27 -0
- package/src/rest/namespaces/video.ts +165 -0
- package/src/rest/pagination.ts +84 -0
- package/src/rest/types.ts +61 -0
- package/src/schema.json +12250 -0
- package/src/skills/SkillBase.ts +547 -0
- package/src/skills/SkillManager.ts +415 -0
- package/src/skills/SkillRegistry.ts +367 -0
- package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
- package/src/skills/builtin/ask_claude.ts +241 -0
- package/src/skills/builtin/claude_skills.ts +978 -0
- package/src/skills/builtin/custom_skills.ts +312 -0
- package/src/skills/builtin/datasphere.ts +438 -0
- package/src/skills/builtin/datasphere_serverless.ts +339 -0
- package/src/skills/builtin/datetime.ts +130 -0
- package/src/skills/builtin/google_maps.ts +651 -0
- package/src/skills/builtin/index.ts +88 -0
- package/src/skills/builtin/info_gatherer.ts +405 -0
- package/src/skills/builtin/joke.ts +191 -0
- package/src/skills/builtin/math.ts +142 -0
- package/src/skills/builtin/mcp_gateway.ts +677 -0
- package/src/skills/builtin/native_vector_search.ts +901 -0
- package/src/skills/builtin/play_background_file.ts +358 -0
- package/src/skills/builtin/spider.ts +869 -0
- package/src/skills/builtin/swml_transfer.ts +635 -0
- package/src/skills/builtin/weather_api.ts +248 -0
- package/src/skills/builtin/web_search.ts +1074 -0
- package/src/skills/builtin/wikipedia_search.ts +299 -0
- package/src/skills/index.ts +12 -0
- package/src/types.ts +132 -0
- package/tests/AgentBase.test.ts +1093 -0
- package/tests/AgentServer.test.ts +126 -0
- package/tests/AuthHandler.test.ts +133 -0
- package/tests/ConfigLoader.test.ts +151 -0
- package/tests/ContextBuilder.test.ts +108 -0
- package/tests/DataMap.test.ts +367 -0
- package/tests/EphemeralSkillCopy.test.ts +107 -0
- package/tests/FunctionResult.test.ts +298 -0
- package/tests/GracefulShutdown.test.ts +46 -0
- package/tests/Logger.test.ts +420 -0
- package/tests/PomBuilder.test.ts +228 -0
- package/tests/ProxyDetection.test.ts +228 -0
- package/tests/SWMLService.test.ts +320 -0
- package/tests/SWMLVerbHandler.test.ts +523 -0
- package/tests/SchemaUtils.test.ts +106 -0
- package/tests/SchemaUtils.verb.test.ts +206 -0
- package/tests/SecurityUtils.test.ts +192 -0
- package/tests/ServerlessAdapter.test.ts +222 -0
- package/tests/SessionManager.test.ts +257 -0
- package/tests/SkillBaseFeatures.test.ts +130 -0
- package/tests/SkillMultiInstance.test.ts +102 -0
- package/tests/SkillParameterSchemas.test.ts +134 -0
- package/tests/SkillRegistrySchema.test.ts +84 -0
- package/tests/SslConfig.test.ts +97 -0
- package/tests/SwmlBuilder.test.ts +400 -0
- package/tests/TypeInference.test.ts +165 -0
- package/tests/VerbHandlerRegistry.test.ts +128 -0
- package/tests/cli/mock-data.test.ts +113 -0
- package/tests/cli/swaig-test.test.ts +108 -0
- package/tests/examples.test.ts +194 -0
- package/tests/fixtures/scrape-parity/README.md +53 -0
- package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
- package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
- package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
- package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
- package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
- package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
- package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
- package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
- package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
- package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
- package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
- package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
- package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
- package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
- package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
- package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
- package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
- package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
- package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
- package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
- package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
- package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
- package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
- package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
- package/tests/fixtures/scrape-parity/python_extract.py +109 -0
- package/tests/livewire/livewire.test.ts +780 -0
- package/tests/mcp.test.ts +221 -0
- package/tests/prefabs/prefabs.test.ts +1093 -0
- package/tests/relay/Action.test.ts +392 -0
- package/tests/relay/Call.test.ts +535 -0
- package/tests/relay/Deferred.test.ts +71 -0
- package/tests/relay/Message.test.ts +164 -0
- package/tests/relay/RelayClient.test.ts +779 -0
- package/tests/relay/RelayEvent.test.ts +463 -0
- package/tests/relay/helpers.ts +79 -0
- package/tests/rest/HttpClient.test.ts +274 -0
- package/tests/rest/RestError.test.ts +53 -0
- package/tests/rest/calling.test.ts +156 -0
- package/tests/rest/client.test.ts +197 -0
- package/tests/rest/compat.test.ts +335 -0
- package/tests/rest/datasphere.test.ts +71 -0
- package/tests/rest/fabric.test.ts +186 -0
- package/tests/rest/helpers.ts +95 -0
- package/tests/rest/logs.test.ts +68 -0
- package/tests/rest/pagination.test.ts +133 -0
- package/tests/rest/registry.test.ts +94 -0
- package/tests/rest/relay-rest.test.ts +290 -0
- package/tests/rest/video.test.ts +173 -0
- package/tests/setup.ts +6 -0
- package/tests/skills/SkillBase.test.ts +108 -0
- package/tests/skills/SkillManager.test.ts +268 -0
- package/tests/skills/SkillRegistry.test.ts +176 -0
- package/tests/skills/builtin.test.ts +1472 -0
- package/tests/skills/claude-skills.test.ts +54 -0
- package/tests/skills/custom-skills.test.ts +53 -0
- package/tests/skills/datasphere-serverless.test.ts +70 -0
- package/tests/skills/datasphere.test.ts +107 -0
- package/tests/skills/datetime.test.ts +101 -0
- package/tests/skills/google-maps.test.ts +78 -0
- package/tests/skills/info-gatherer.test.ts +411 -0
- package/tests/skills/joke.test.ts +81 -0
- package/tests/skills/math.test.ts +68 -0
- package/tests/skills/mcp-gateway.test.ts +101 -0
- package/tests/skills/play-background.test.ts +54 -0
- package/tests/skills/spider.test.ts +108 -0
- package/tests/skills/swml-transfer.test.ts +178 -0
- package/tests/skills/trivia.test.ts +54 -0
- package/tests/skills/vector-search.test.ts +135 -0
- package/tests/skills/weather-api.test.ts +77 -0
- package/tests/skills/web-search-parity.test.ts +59 -0
- package/tests/skills/web-search.test.ts +103 -0
- package/tests/skills/wikipedia.test.ts +63 -0
- package/tsconfig.json +18 -0
- package/vitest.config.ts +9 -0
|
@@ -0,0 +1,415 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* SkillManager - Manages skill lifecycle for an agent.
|
|
3
|
+
*
|
|
4
|
+
* Handles loading, unloading, validation, and injection of
|
|
5
|
+
* skill tools, hints, global data, and prompt sections.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { SkillBase, type SkillConfig } from './SkillBase.js';
|
|
9
|
+
import { SkillRegistry } from './SkillRegistry.js';
|
|
10
|
+
import { getLogger } from '../Logger.js';
|
|
11
|
+
|
|
12
|
+
const log = getLogger('SkillManager');
|
|
13
|
+
|
|
14
|
+
/** Stored metadata for a loaded skill, enabling ephemeral copy re-instantiation. */
|
|
15
|
+
interface SkillMetaEntry {
|
|
16
|
+
/** The skill class constructor. */
|
|
17
|
+
SkillClass: typeof SkillBase;
|
|
18
|
+
/** The config originally passed to the skill. */
|
|
19
|
+
config: SkillConfig;
|
|
20
|
+
/** The skill name. */
|
|
21
|
+
skillName: string;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Manages the lifecycle of skills attached to an agent.
|
|
26
|
+
*
|
|
27
|
+
* Handles loading, unloading, validation, and aggregation of skill tools,
|
|
28
|
+
* hints, global data, and prompt sections.
|
|
29
|
+
*
|
|
30
|
+
* @remarks
|
|
31
|
+
* **Architectural note — push vs pull model:**
|
|
32
|
+
* Python's `SkillManager.__init__(self, agent)` stores the agent reference and
|
|
33
|
+
* uses a **push model**: when a skill is loaded via `load_skill()`, the manager
|
|
34
|
+
* immediately calls `agent.add_hints()`, `agent.update_global_data()`, and
|
|
35
|
+
* `agent.prompt_add_section()` to inject skill data into the agent.
|
|
36
|
+
*
|
|
37
|
+
* This TypeScript implementation uses a **pull model** instead: `SkillManager`
|
|
38
|
+
* has no agent reference and no constructor. `AgentBase` owns the manager and
|
|
39
|
+
* calls `getAllHints()`, `getMergedGlobalData()`, and `getAllPromptSections()`
|
|
40
|
+
* at render time. Both approaches produce the same observable behavior at the
|
|
41
|
+
* SWML / SWAIG level. The pull model avoids circular-reference issues between
|
|
42
|
+
* `AgentBase` and `SkillManager` and is better suited to TypeScript's
|
|
43
|
+
* import-graph constraints.
|
|
44
|
+
*/
|
|
45
|
+
export class SkillManager {
|
|
46
|
+
private skills: Map<string, SkillBase> = new Map();
|
|
47
|
+
private skillMeta: Map<string, SkillMetaEntry> = new Map();
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Public read-only view of all loaded skill instances, keyed by instance key.
|
|
51
|
+
* Python equivalent: `self.loaded_skills` (public `Dict[str, SkillBase]`).
|
|
52
|
+
*
|
|
53
|
+
* Use this to iterate or inspect loaded skills without mutating the internal map.
|
|
54
|
+
*/
|
|
55
|
+
get loadedSkills(): ReadonlyMap<string, SkillBase> {
|
|
56
|
+
return this.skills;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Add a skill to the manager, validating env vars and calling setup().
|
|
61
|
+
* Uses the skill's instance key for deduplication.
|
|
62
|
+
*
|
|
63
|
+
* Throws on duplicate (when multi-instance is disallowed), missing env vars,
|
|
64
|
+
* or setup errors. {@link loadSkill} / {@link loadSkillByName} wrap this and
|
|
65
|
+
* catch to return `[false, msg]`, matching Python `load_skill`'s return
|
|
66
|
+
* contract (`skill_manager.py` lines 114-118).
|
|
67
|
+
*
|
|
68
|
+
* @param skill - The skill instance to add.
|
|
69
|
+
*/
|
|
70
|
+
async addSkill(skill: SkillBase): Promise<void> {
|
|
71
|
+
const name = skill.skillName;
|
|
72
|
+
const instanceKey = skill.getInstanceKey();
|
|
73
|
+
const SkillClass = skill.constructor as typeof SkillBase;
|
|
74
|
+
|
|
75
|
+
// Duplicate detection using instance key
|
|
76
|
+
if (this.skills.has(instanceKey)) {
|
|
77
|
+
if (!SkillClass.SUPPORTS_MULTIPLE_INSTANCES) {
|
|
78
|
+
throw new Error(`Skill '${name}' is already loaded and does not support multiple instances`);
|
|
79
|
+
}
|
|
80
|
+
log.warn(`Skill '${name}' with key '${instanceKey}' already loaded, skipping duplicate`);
|
|
81
|
+
return;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
// Validate required env vars — throw on miss; loadSkill/loadSkillByName
|
|
85
|
+
// catch and convert to `[false, msg]` to match Python load_skill's return
|
|
86
|
+
// contract (skill_manager.py lines 114-118).
|
|
87
|
+
const missingEnvVars = skill.validateEnvVars();
|
|
88
|
+
if (missingEnvVars.length > 0) {
|
|
89
|
+
throw new Error(`Cannot load skill '${name}': missing environment variables: ${missingEnvVars.join(', ')}`);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
// Parameter schema contract — partial port of Python load_skill checks
|
|
93
|
+
// (skill_manager.py:49-93). Python additionally requires the subclass to
|
|
94
|
+
// override get_parameter_schema; we skip that identity check because TS
|
|
95
|
+
// test fixtures and trivial skills routinely inherit the base schema
|
|
96
|
+
// without harm, and the TS type system already enforces that
|
|
97
|
+
// getParameterSchema is a callable classmethod returning the right shape.
|
|
98
|
+
const schema = SkillClass.getParameterSchema();
|
|
99
|
+
if (!schema || typeof schema !== 'object' || Object.keys(schema).length === 0) {
|
|
100
|
+
throw new Error(
|
|
101
|
+
`Skill '${name}'.getParameterSchema() must return a non-empty object`,
|
|
102
|
+
);
|
|
103
|
+
}
|
|
104
|
+
log.debug(`Skill '${name}' has ${Object.keys(schema).length} config params`);
|
|
105
|
+
|
|
106
|
+
// Validate required packages — Python equivalent at skill_manager.py:121-131.
|
|
107
|
+
// Throw on miss; wrappers catch and convert to [false, msg].
|
|
108
|
+
const missingPackages = await skill.validatePackages();
|
|
109
|
+
if (missingPackages.length > 0) {
|
|
110
|
+
throw new Error(
|
|
111
|
+
`Cannot load skill '${name}': missing required packages: ${missingPackages.join(', ')}`,
|
|
112
|
+
);
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
// Setup — returns boolean indicating success. Matches Python load_skill
|
|
116
|
+
// (skill_manager.py:134-137): setup() returning false is fatal, the skill
|
|
117
|
+
// is NOT registered, and the caller gets [false, msg] via the wrappers.
|
|
118
|
+
// Python fails closed so the AI never sees a tool whose skill knows it
|
|
119
|
+
// isn't configured correctly.
|
|
120
|
+
const setupOk = await skill.setup();
|
|
121
|
+
if (!setupOk) {
|
|
122
|
+
throw new Error(`Failed to setup skill '${name}'`);
|
|
123
|
+
}
|
|
124
|
+
skill.markInitialized();
|
|
125
|
+
|
|
126
|
+
this.skills.set(instanceKey, skill);
|
|
127
|
+
this.skillMeta.set(instanceKey, {
|
|
128
|
+
SkillClass,
|
|
129
|
+
config: { ...skill['config'] },
|
|
130
|
+
skillName: name,
|
|
131
|
+
});
|
|
132
|
+
log.debug(`Added skill '${name}' (key: ${instanceKey})`);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Remove a skill by its instance key or instance ID, calling cleanup() before removal.
|
|
137
|
+
* @param keyOrId - The instance key or instance ID of the skill to remove.
|
|
138
|
+
* @returns True if the skill was found and removed, false otherwise.
|
|
139
|
+
*
|
|
140
|
+
* @remarks Equivalent to Python's `unload_skill(skill_identifier)`. Callers porting
|
|
141
|
+
* from Python should change `skill_manager.unload_skill(id)` →
|
|
142
|
+
* `skillManager.removeSkill(id)`.
|
|
143
|
+
*/
|
|
144
|
+
async removeSkill(keyOrId: string): Promise<boolean> {
|
|
145
|
+
// Try by instance key first
|
|
146
|
+
let skill = this.skills.get(keyOrId);
|
|
147
|
+
let key = keyOrId;
|
|
148
|
+
|
|
149
|
+
// Fallback: search by instanceId for backward compatibility
|
|
150
|
+
if (!skill) {
|
|
151
|
+
for (const [k, s] of this.skills) {
|
|
152
|
+
if (s.instanceId === keyOrId) {
|
|
153
|
+
skill = s;
|
|
154
|
+
key = k;
|
|
155
|
+
break;
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
if (!skill) return false;
|
|
161
|
+
|
|
162
|
+
await skill.cleanup();
|
|
163
|
+
this.skills.delete(key);
|
|
164
|
+
this.skillMeta.delete(key);
|
|
165
|
+
log.debug(`Removed skill '${skill.skillName}' (${key})`);
|
|
166
|
+
return true;
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* Remove all skill instances matching a given skill name.
|
|
171
|
+
* @param skillName - The skill name to match against.
|
|
172
|
+
* @returns The number of skill instances removed.
|
|
173
|
+
*/
|
|
174
|
+
async removeSkillByName(skillName: string): Promise<number> {
|
|
175
|
+
let count = 0;
|
|
176
|
+
for (const [key, skill] of this.skills) {
|
|
177
|
+
if (skill.skillName === skillName) {
|
|
178
|
+
await skill.cleanup();
|
|
179
|
+
this.skills.delete(key);
|
|
180
|
+
this.skillMeta.delete(key);
|
|
181
|
+
count++;
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
return count;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Check if any skill instance with the given name is currently loaded.
|
|
189
|
+
* @param skillName - The skill name to check for.
|
|
190
|
+
* @returns True if at least one instance with this name is loaded.
|
|
191
|
+
*/
|
|
192
|
+
hasSkill(skillName: string): boolean {
|
|
193
|
+
for (const skill of this.skills.values()) {
|
|
194
|
+
if (skill.skillName === skillName) return true;
|
|
195
|
+
}
|
|
196
|
+
return false;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Check if a skill with the given instance key is currently loaded.
|
|
201
|
+
* This matches Python's `has_skill` semantics, which performs a direct
|
|
202
|
+
* dictionary key lookup (`skill_identifier in self.loaded_skills`).
|
|
203
|
+
*
|
|
204
|
+
* Use `hasSkill(name)` to check by skill name (iterates values).
|
|
205
|
+
* Use `hasSkillByKey(key)` to check by instance key (direct map lookup).
|
|
206
|
+
*
|
|
207
|
+
* @param instanceKey - The instance key to look up.
|
|
208
|
+
* @returns True if a skill with this exact instance key is loaded.
|
|
209
|
+
*
|
|
210
|
+
* @remarks Equivalent to Python's `has_skill(skill_identifier)`. Callers porting
|
|
211
|
+
* from Python should change `skill_manager.has_skill(key)` →
|
|
212
|
+
* `skillManager.hasSkillByKey(key)`.
|
|
213
|
+
*/
|
|
214
|
+
hasSkillByKey(instanceKey: string): boolean {
|
|
215
|
+
return this.skills.has(instanceKey);
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* Load a skill by providing the class constructor directly, bypassing the registry.
|
|
220
|
+
* This is the TypeScript equivalent of Python's `load_skill(skill_name, skill_class, params)`
|
|
221
|
+
* path where a caller-provided `skill_class` is used instead of a registry lookup.
|
|
222
|
+
*
|
|
223
|
+
* @param skillClass - The skill class constructor (a subclass of `SkillBase`).
|
|
224
|
+
* @param config - Optional configuration to pass to the skill constructor.
|
|
225
|
+
* @returns A tuple `[success, errorMessage]` matching Python's `load_skill` return
|
|
226
|
+
* contract. `errorMessage` is an empty string on success.
|
|
227
|
+
*
|
|
228
|
+
* @remarks Equivalent to Python's `load_skill(skill_name, skill_class=MySkillClass, params)`.
|
|
229
|
+
*
|
|
230
|
+
* @example
|
|
231
|
+
* ```ts
|
|
232
|
+
* const [ok, err] = await manager.loadSkill(MyCustomSkill, { api_key: 'secret' });
|
|
233
|
+
* if (!ok) console.error(err);
|
|
234
|
+
* ```
|
|
235
|
+
*/
|
|
236
|
+
async loadSkill(skillClass: typeof SkillBase, config?: SkillConfig): Promise<[boolean, string]> {
|
|
237
|
+
try {
|
|
238
|
+
// Concrete skill subclasses override the constructor to take only (config?: SkillConfig).
|
|
239
|
+
// Cast to reflect actual runtime signature — the base class requires `skillName` but
|
|
240
|
+
// concrete subclasses hardcode it in super(...), so only config is needed at the call site.
|
|
241
|
+
const SkillCtor = skillClass as unknown as new (config?: SkillConfig) => SkillBase;
|
|
242
|
+
const skill = new SkillCtor(config);
|
|
243
|
+
await this.addSkill(skill);
|
|
244
|
+
return [true, ''];
|
|
245
|
+
} catch (err) {
|
|
246
|
+
const errorMsg = `Error loading skill: ${err instanceof Error ? err.message : String(err)}`;
|
|
247
|
+
log.error(errorMsg);
|
|
248
|
+
return [false, errorMsg];
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* Load a skill by name from the global SkillRegistry, construct it, and add it.
|
|
254
|
+
* This is the TypeScript equivalent of Python's `load_skill(skill_name)` path
|
|
255
|
+
* where `skill_class=None` triggers a registry lookup.
|
|
256
|
+
*
|
|
257
|
+
* @param skillName - The registered skill name to look up in the SkillRegistry.
|
|
258
|
+
* @param config - Optional configuration to pass to the skill factory.
|
|
259
|
+
* @returns A tuple `[success, errorMessage]` matching Python's `load_skill` return
|
|
260
|
+
* contract. `errorMessage` is an empty string on success.
|
|
261
|
+
*
|
|
262
|
+
* @remarks Equivalent to Python's `load_skill(skill_name)` (registry path, where
|
|
263
|
+
* `skill_class=None`). Callers porting from Python should change
|
|
264
|
+
* `skill_manager.load_skill(name)` → `skillManager.loadSkillByName(name)`.
|
|
265
|
+
*/
|
|
266
|
+
async loadSkillByName(skillName: string, config?: SkillConfig): Promise<[boolean, string]> {
|
|
267
|
+
const registry = SkillRegistry.getInstance();
|
|
268
|
+
|
|
269
|
+
if (!registry.has(skillName)) {
|
|
270
|
+
const errorMsg = `Skill '${skillName}' not found in registry`;
|
|
271
|
+
log.error(errorMsg);
|
|
272
|
+
return [false, errorMsg];
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
const skill = registry.create(skillName, config);
|
|
276
|
+
if (!skill) {
|
|
277
|
+
const errorMsg = `Failed to create skill '${skillName}' from registry`;
|
|
278
|
+
log.error(errorMsg);
|
|
279
|
+
return [false, errorMsg];
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
try {
|
|
283
|
+
await this.addSkill(skill);
|
|
284
|
+
return [true, ''];
|
|
285
|
+
} catch (err) {
|
|
286
|
+
const errorMsg = `Error loading skill '${skillName}': ${err instanceof Error ? err.message : String(err)}`;
|
|
287
|
+
log.error(errorMsg);
|
|
288
|
+
return [false, errorMsg];
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
/**
|
|
293
|
+
* List the instance keys of all currently loaded skills.
|
|
294
|
+
* Python equivalent: `list_loaded_skills() -> List[str]` which returns
|
|
295
|
+
* `list(self.loaded_skills.keys())`.
|
|
296
|
+
*
|
|
297
|
+
* Use `listSkills()` for richer objects (name, instanceId, initialized).
|
|
298
|
+
* Use `listSkillKeys()` for a flat list of instance key strings.
|
|
299
|
+
*
|
|
300
|
+
* @returns Array of instance key strings.
|
|
301
|
+
*
|
|
302
|
+
* @remarks Equivalent to Python's `list_loaded_skills()`. Callers porting from
|
|
303
|
+
* Python should change `skill_manager.list_loaded_skills()` →
|
|
304
|
+
* `skillManager.listSkillKeys()`.
|
|
305
|
+
*/
|
|
306
|
+
listSkillKeys(): string[] {
|
|
307
|
+
return Array.from(this.skills.keys());
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/**
|
|
311
|
+
* Get a skill by its instance key or instance ID.
|
|
312
|
+
* @param keyOrId - The instance key or instance ID to look up.
|
|
313
|
+
* @returns The skill instance, or undefined if not found.
|
|
314
|
+
*/
|
|
315
|
+
getSkill(keyOrId: string): SkillBase | undefined {
|
|
316
|
+
const skill = this.skills.get(keyOrId);
|
|
317
|
+
if (skill) return skill;
|
|
318
|
+
// Fallback: search by instanceId
|
|
319
|
+
for (const s of this.skills.values()) {
|
|
320
|
+
if (s.instanceId === keyOrId) return s;
|
|
321
|
+
}
|
|
322
|
+
return undefined;
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
/**
|
|
326
|
+
* List all loaded skill instances with their name, ID, and initialization state.
|
|
327
|
+
* @returns Array of skill summary objects.
|
|
328
|
+
*/
|
|
329
|
+
listSkills(): { name: string; instanceId: string; initialized: boolean }[] {
|
|
330
|
+
return Array.from(this.skills.values()).map(s => ({
|
|
331
|
+
name: s.skillName,
|
|
332
|
+
instanceId: s.instanceId,
|
|
333
|
+
initialized: s.isInitialized(),
|
|
334
|
+
}));
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
/**
|
|
338
|
+
* Aggregate tool definitions from all loaded skills.
|
|
339
|
+
* @returns Combined array of all skill tool definitions.
|
|
340
|
+
*/
|
|
341
|
+
getAllTools(): ReturnType<SkillBase['getTools']> {
|
|
342
|
+
const tools: ReturnType<SkillBase['getTools']> = [];
|
|
343
|
+
for (const skill of this.skills.values()) {
|
|
344
|
+
tools.push(...skill.getTools());
|
|
345
|
+
}
|
|
346
|
+
return tools;
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
/**
|
|
350
|
+
* Aggregate prompt sections from all loaded skills.
|
|
351
|
+
* @returns Combined array of all skill prompt sections.
|
|
352
|
+
*/
|
|
353
|
+
getAllPromptSections(): ReturnType<SkillBase['getPromptSections']> {
|
|
354
|
+
const sections: ReturnType<SkillBase['getPromptSections']> = [];
|
|
355
|
+
for (const skill of this.skills.values()) {
|
|
356
|
+
sections.push(...skill.getPromptSections());
|
|
357
|
+
}
|
|
358
|
+
return sections;
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
/**
|
|
362
|
+
* Aggregate speech recognition hints from all loaded skills.
|
|
363
|
+
* @returns Combined array of all skill hint strings.
|
|
364
|
+
*/
|
|
365
|
+
getAllHints(): string[] {
|
|
366
|
+
const hints: string[] = [];
|
|
367
|
+
for (const skill of this.skills.values()) {
|
|
368
|
+
hints.push(...skill.getHints());
|
|
369
|
+
}
|
|
370
|
+
return hints;
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
/**
|
|
374
|
+
* Merge global data from all loaded skills into a single object.
|
|
375
|
+
* @returns Combined global data (later skills override earlier ones on key conflicts).
|
|
376
|
+
*/
|
|
377
|
+
getMergedGlobalData(): Record<string, unknown> {
|
|
378
|
+
const data: Record<string, unknown> = {};
|
|
379
|
+
for (const skill of this.skills.values()) {
|
|
380
|
+
Object.assign(data, skill.getGlobalData());
|
|
381
|
+
}
|
|
382
|
+
return data;
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
/**
|
|
386
|
+
* Get the number of currently loaded skill instances.
|
|
387
|
+
* @returns The count of loaded skills.
|
|
388
|
+
*/
|
|
389
|
+
get size(): number {
|
|
390
|
+
return this.skills.size;
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
/**
|
|
394
|
+
* Get metadata for all loaded skills, enabling ephemeral copy re-instantiation.
|
|
395
|
+
* @returns Array of entries containing skill name, class constructor, and config.
|
|
396
|
+
*/
|
|
397
|
+
getLoadedSkillEntries(): Array<{ skillName: string; SkillClass: typeof SkillBase; config: SkillConfig }> {
|
|
398
|
+
return Array.from(this.skillMeta.values()).map(entry => ({
|
|
399
|
+
skillName: entry.skillName,
|
|
400
|
+
SkillClass: entry.SkillClass,
|
|
401
|
+
config: { ...entry.config },
|
|
402
|
+
}));
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
/**
|
|
406
|
+
* Remove all skills and clean up.
|
|
407
|
+
*/
|
|
408
|
+
async clear(): Promise<void> {
|
|
409
|
+
for (const skill of this.skills.values()) {
|
|
410
|
+
await skill.cleanup();
|
|
411
|
+
}
|
|
412
|
+
this.skills.clear();
|
|
413
|
+
this.skillMeta.clear();
|
|
414
|
+
}
|
|
415
|
+
}
|