TS SDK release docs#301
Merged
Devon-White merged 24 commits intomainfrom Apr 27, 2026
Merged
Conversation
Audit sweep against signalwire-typescript@ba6d5b1. Covers agent-base,
agent-server, prefabs, skills, swaig-function, swml-builder,
swml-service, and all 7 configuration sub-classes (session-manager,
schema-utils, prompt-manager, config-loader, serverless-adapter,
ssl-config, auth-handler).
Notable fixes:
- session-manager/debug-token: wrong return shape (flat camelCase
|null) vs nested DebugTokenResult with snake_case components/status
- session-manager/get-session-metadata: typed `| undefined` but src
uses `?? {}` — never undefined
- auth-handler/middleware: `optional` param entirely undocumented
- set-global-data / update-global-data: claimed "replace" but src
uses safeAssign (merge)
- on-function-call: Warning said hook can't intercept but src uses
hookResult to short-circuit
- swml-builder/say: doc claimed method didn't exist (src 195 defines
it)
- skills/google-maps, native-vector-search, play-background-file:
wrong/missing tool names and config
- Multiple stub pages fleshed out (reset-contexts, set-pronunciations,
validate-tool-token, et al.)
Tracker updated with per-class status and P4 coverage gaps for
follow-up (config-loader mergeWithEnv/getSection, auth-handler
verify* + expressMiddleware, swml-service ~14 undocumented methods).
Adds 48 per-method pages across 8 agent classes flagged as P4 coverage
gaps in the audit tracker. Each class's index.mdx CardGroup is
expanded
to link the new pages. New pages follow the standard format
(frontmatter
→ link refs → overview → params → returns → example) and note
TS/Python
divergences where behavior differs.
Breakdown:
- swml-service (14): reset-document, stop, get-document,
render-document,
get-basic-auth-credentials, serve, as-router, add-section,
add-verb-to-section, register-verb-handler,
register-routing-callback,
extract-sip-username, manual-set-proxy-url, on-request
- configuration/auth-handler (5): verify-basic-auth,
verify-bearer-token,
verify-api-key, get-auth-info, express-middleware
- configuration/config-loader (8): find-config-file, get-config,
get-config-file, has-config, get-section, substitute-vars,
merge-with-env, interpolate-env-vars
- pom-builder (5): reset, add-pom-as-subsection, to-json,
from-sections,
render-xml
- swml-builder (5): build, render, document, set-validation,
add-section
- skill-base (7): get-agent, set-agent, get-config, define-tool,
has-all-env-vars, has-all-packages, validate-packages
- skill-registry (3): get-skill-class, list-skills, reset-instance
- skill-manager (1): loaded-skills
Also quotes the YAML-unsafe description in swml-builder/say.mdx (colon
in "say: prefix" was breaking fern check).
yarn fern-md-check: 2241 files valid. yarn fern-check: 0 errors.
Fixes defaults, values, and coverage in agents/configuration/
environment-variables.mdx to match what the TS SDK actually does.
Corrected defaults:
- SWML_MAX_REQUEST_SIZE: 10485760 -> 1048576 (description 10 MB -> 1
MB)
to match AgentBase.ts:2011.
- SWML_RATE_LIMIT: dropped default=60; unset means no rate limiting
(AgentBase.ts:2046 only installs the middleware when the var is
set).
- SWML_ALLOWED_HOSTS: dropped default="*"; unset means no host check
(AgentBase.ts:2033 applies the middleware only when set).
- SWML_BASIC_AUTH_USER: dropped default="signalwire"; fallback is the
agent's `name` (AgentBase.ts:220).
- SIGNALWIRE_LOG_MODE: removed unrecognized "default" value from the
accepted-values list; Logger.ts only handles off|stderr|auto.
Removed env vars:
- APP_URL: no references in TS SDK source (grep shows zero hits);
the proxy Warning was also updated to drop the APP_URL mention.
- SWML_REQUEST_TIMEOUT: AgentBase.ts:2010 reads the var but never uses
the resulting value — dead code. Doc described behavior that does
not
exist.
Added env vars (present in source, missing from docs):
- SWML_TRUST_PROXY_HEADERS (AgentBase.ts:125) — trust X-Forwarded-*
headers when set to "true".
- SWML_CSRF_PROTECTION (AgentBase.ts:2085) — reject POSTs whose Origin
is not in SWML_CORS_ORIGINS when set to "true".
Example .env updated: SIGNALWIRE_LOG_MODE=default -> =auto.
Datasphere skill SIGNALWIRE_TOKEN usage (skills/datasphere.mdx) is
intentionally left unchanged — it matches current SDK source
(skills/builtin/datasphere.ts:98). The split between skill auth
(SIGNALWIRE_TOKEN) and client auth (SIGNALWIRE_API_TOKEN) exists in
both the TS and Python SDKs and is not a TS-specific bug.
yarn fern-md-check: 2241 valid. yarn fern-check: 0 errors.
Contributor
relay/constants.mdx listed 76 constants; only 39 are re-exported from @signalwire/sdk. Trim doc to the exported subset, matching Python's signalwire/relay/__init__.py __all__ surface. Dropped sections (internal-only): Protocol, JSON-RPC Methods, End Reasons, Play/Record/Detect/Room States, Reconnect Settings, Authorization Event, CALL_STATES/MESSAGE_TERMINAL_STATES arrays. The <Note> about partial re-exports is no longer needed. String enum values users see at runtime (endReason, play/record/detect states) are already documented inline on events.mdx. No inbound anchor links broken.
Uncomment TS tabs, fix signalwire-agents → @signalwire/sdk,
normalize defineTool parameters to valid JSON Schema across
getting-started/{overview,installation,quickstart,dev-environment}.
Pilot for wider 51-file guides sweep. Findings at
docs/temp/guides-audit/getting-started/findings.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Uncomment TS tabs, swap signalwire-agents → @signalwire/sdk, and fix
TS-specific drift across guides/{build-ai-agents,deploy,make-and-receive-calls,
manage-resources}/.
Key fixes:
- Pkg name: signalwire-agents → @signalwire/sdk across every TS tab.
- Unwrap {/* ... */} around TypeScript <Tab> blocks (other-language
tabs stay commented per release scope).
- Subpath imports removed (@signalwire/sdk has no subpath exports).
- defineTool parameters: flat maps and empty {} → full JSON Schema
{ type: 'object', properties: {...}, required: [...] }.
- addSkill('name', opts) → addSkillByName('name', opts); config keys
switched to snake_case (Python parity; read via this.getConfig).
- SkillBase contract: setup(agent) → async setup(): Promise<boolean>;
registerTools() removed; declare tools in setup() via this.defineTool.
- FunctionResult.connect / swmlTransfer / stopRecordCall: options-object
calls → positional args (src/FunctionResult.ts:112/134/520).
- addLanguage(name, code, voice) positional → { name, code, voice } object.
- promptAddSection('Role', 'body') positional → ('Role', { body }).
- LanguageConfig fillers / functionFillers: flat arrays → Record shapes.
- RelayClient / RestClient ctor: projectId/apiToken/spaceName →
project/token/host.
- onSummary: misused as agent.onSummary(cb) → subclass override pattern.
- Serverless: agent.handleRequest(event, ctx) → agent.runServerless(...)
or ServerlessAdapter.createGcfHandler/createAzureHandler(agent.getApp()).
- ESM-only notes added to deploy overview/production/docker/serverless;
node entry switched to .mjs for PM2/systemd/Lambda patterns.
- Loader: npx ts-node → npx tsx in testing + deploy overview (matches
getting-started pilot).
- _render_swml() prose made language-agnostic (renderSwml in TS).
- recordCall 'mp4' format scoped to Python (TS type is 'wav' | 'mp3').
- InfoGathererAgent questions: keyName/questionText → key_name/question_text
(snake_case per src/prefabs/InfoGathererAgent.ts:17-22).
- SUPPORTS_MULTIPLE → SUPPORTS_MULTIPLE_INSTANCES in custom-skills table.
- skillRegistry.addSkillDirectory → SkillRegistry.getInstance().
discoverFromDirectory.
Out of scope (flagged in findings):
- Authoring new TS tabs where Python-only examples don't port cleanly
(security SSL, search-knowledge pgvector, cgi-mode Node CGI).
- Large per-skill parameter-table drift in builtin-skills.mdx (needs
separate per-skill source-verification pass).
Findings under docs/temp/guides-audit/<chunk>/findings.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add api_ninjas_trivia, ask_claude, custom_skills, datasphere_serverless, and spider to the Available Skills and Skills Summary tables in builtin-skills.mdx and to the Available Built-in Skills table in understanding-skills.mdx. Multi-instance flags sourced from each skill's SUPPORTS_MULTIPLE_INSTANCES declaration in src/skills/builtin/. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
deploy/serverless.mdx: collapse blank line at L23 between the Python
and TypeScript rows of the "Language support for serverless" table so
both rows render as one contiguous table.
deploy/cgi-mode.mdx: move the TypeScript row into the `{/* */}` block
that wraps the other non-TS language rows.
security.mdx: pair the two Python code blocks that port cleanly with
matching TypeScript tabs, and scope the direct-SSL example to Python.
- Credentials in Your Agent (L88): TS tab using AgentBase with
basicAuth: [user, pass] reading from SWML_BASIC_AUTH_USER /
SWML_BASIC_AUTH_PASSWORD env vars.
- Function Token Security example (L166): TS tab showing a
SecureAgent subclass calling defineTool({ ..., secure: true }).
- SSL Configuration (L264): annotated with a Note explaining that
TypeScript AgentBase.serve() does not accept SSL arguments —
directs readers to the reverse-proxy pattern below (recommended)
or the WebService reference for programmatic SSL.
search-knowledge.mdx: the TS NativeVectorSearchSkill source declares
`backend: 'pgvector'`, `connection_string`, and `collection_name` at
native_vector_search.ts:308-355 — pgvector is a supported TS config
path, not Python-only as previously assumed.
- pgvector Backend section: add a TypeScript tab alongside the
existing Python example using addSkillByName('native_vector_search',
{ backend: 'pgvector', connection_string, collection_name, ... }).
- Rename `distance_threshold` → `similarity_threshold` throughout.
The TS source (native_vector_search.ts:797) and the Python source
(skill.py:253) both use `similarity_threshold`; the doc was wrong
for both SDKs. Also clarified that higher is better.
builtin-skills.mdx: parameter tables for 11 skills had drifted from each skill's getParameterSchema(). Rebuilt every table against signalwire-typescript/src/skills/builtin/<skill>.ts, cross-checked against signalwire-python/.../skills/<skill>/skill.py where relevant. - datetime and math: replaced Parameters tables with "no configuration parameters" note. Verified in both Python (datetime/skill.py:118, math/skill.py:136) and TypeScript — neither skill declares custom params. Removed the `default_timezone` config from the add-skill example at L72 (it never existed). - web_search: add `delay`, `max_content_length`, `oversample_factor`, `no_results_message`, `safe_search`; drop phantom `tool_description`. - wikipedia_search: replace `language`/`sentences`/`tool_name` (none exist) with `num_results` and `no_results_message`. - weather_api: add `units` enum; drop `tool_description`. - joke: drop phantom `category`. - play_background_file: full rewrite. Document catalog mode (`files`) and free-form mode (`default_file_url`/`allowed_domains`); remove non-existent `audio_url`/`volume`/`loop`/split tool_name_*. - swml_transfer: add Parameters table (didn't exist); list `transfers`, `patterns`, `allow_arbitrary`, `tool_name`, `description`, `parameter_name`, `parameter_description`, `default_message`, `default_post_process`, `required_fields`. - datasphere: add Parameters table; rename `api_token` → `token`; add `document_id`, `count`, `distance`, `tags`, `language`, `pos_to_expand`, `max_synonyms`, `no_results_message`. - native_vector_search: add Parameters table; rename `index_path` → `index_file`; add `backend` (sqlite/pgvector), `connection_string`, `collection_name`, `build_index`, `source_dir`, `remote_url`, `index_name`, `similarity_threshold`, `tags`, `global_tags`, `file_types`, `exclude_patterns`, `no_results_message`, `response_prefix`, `response_postfix`, `max_content_length`, `description`. - google_maps: add `geocode_tool_name`, `route_by_coords_tool_name`, `default_mode` enum. - info_gatherer: add `completion_message`; clarify `questions` shape. - claude_skills: add `include`, `exclude`, `prompt_title`, `prompt_intro`, `skill_descriptions`, `response_prefix`, `response_postfix`, `allow_shell_injection`, `allow_script_execution`, `ignore_invocation_control`, `shell_timeout`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Comprehensive public documentation overhaul for the TypeScript version of the SignalWire Server SDK.