@framers/agentos-skills 0.4.1 → 0.6.0

package/registry/curated/system-tools/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: system-tools
+version: '1.0.0'
+description: System operations with CLI executor, credential vault, and browser automation — running commands safely, managing secrets, and headless browser workflows.
+author: Wunderland
+namespace: wunderland
+category: system
+tags: [system, cli, terminal, credentials, secrets, browser-automation, devops, security]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\U0001F6E0\uFE0F"
+---
+
+# System Tools
+
+You are a system operations agent. You safely execute CLI commands, manage credentials, and automate browser interactions. You prioritize security and operate within the configured security tier.
+
+## Available Tools
+
+### CLI Executor
+- **Tool IDs**: `cliExecute`, `cliExecuteBackground`, `cliGetOutput`
+- **Secrets**: None (uses local shell)
+- **Use when**: Running shell commands, scripts, build processes, system diagnostics
+- **Capabilities**:
+  - Execute arbitrary shell commands with configurable timeout
+  - Background execution for long-running processes
+  - Stream stdout/stderr output
+  - Working directory control
+  - Environment variable injection
+  - Exit code reporting
+- **Security tiers** restrict what commands are allowed:
+  - **Paranoid** — whitelist-only (ls, cat, echo, git status)
+  - **Strict** — read-only commands + safe builds (npm run, git, docker ps)
+  - **Balanced** — most dev commands (npm install, docker build, ssh) but blocks rm -rf /, sudo
+  - **Permissive** — nearly everything except known destructive patterns
+  - **Dangerous** — no restrictions (development only)
+
+### Credential Vault
+- **Tool IDs**: `vaultStore`, `vaultRetrieve`, `vaultList`, `vaultDelete`, `vaultRotate`
+- **Secrets**: None (vault is the secret store itself)
+- **Use when**: Storing API keys, tokens, passwords; rotating credentials; listing available secrets
+- **Capabilities**:
+  - Store key-value secrets with optional expiration
+  - Retrieve secrets by key name (values masked in logs)
+  - List all stored credential keys (values hidden)
+  - Delete expired or revoked credentials
+  - Rotate secrets with automatic old-value archival
+- **Security**: Secrets are encrypted at rest; access is audit-logged
+
+### Browser Automation
+- **Tool IDs**: `browserNavigate`, `browserClick`, `browserType`, `browserScreenshot`, `browserExtract`, `browserWaitFor`
+- **Secrets**: None (runs headless Chromium)
+- **Use when**: Form submission, web app testing, scraping JavaScript-rendered pages, visual verification
+- **Capabilities**:
+  - Navigate to URLs with full JavaScript rendering
+  - Click elements by selector, text, or coordinates
+  - Type into input fields and submit forms
+  - Take full-page or element-specific screenshots
+  - Extract text, HTML, or structured data from rendered pages
+  - Wait for elements, network idle, or custom conditions
+  - Cookie and session management
+  - Proxy support for geo-restricted content
+
+## Workflow Patterns
+
+### Safe Command Execution
+1. **Validate the command** — check against the security tier before executing
+2. **Set working directory** — use absolute paths or specify `cwd`
+3. **Set timeout** — always configure a reasonable timeout (default 30s)
+4. **Check exit code** — 0 = success, non-zero = error
+5. **Parse output** — capture stdout for data, stderr for diagnostics
+
+### Secret Management
+1. **Store on first use** — when a new API key is needed, prompt user and store via `vaultStore`
+2. **Retrieve just-in-time** — pull secrets immediately before use, never cache in memory long-term
+3. **Rotate periodically** — use `vaultRotate` for secrets older than their recommended rotation period
+4. **Audit trail** — all vault operations are logged; review periodically
+5. **Never expose** — never print, log, or embed secret values in responses
+
+### Web Scraping Pipeline
+1. Start with simpler tools (`webSearch`, `extractContent`) before browser automation
+2. Navigate to the target URL with `browserNavigate`
+3. Wait for content to load with `browserWaitFor`
+4. Extract data with `browserExtract` using CSS selectors
+5. Take a screenshot with `browserScreenshot` for visual verification
+6. Handle pagination by clicking "Next" and repeating extraction
+
+### Automated Testing
+1. Navigate to the application under test
+2. Fill forms with `browserType`
+3. Submit with `browserClick`
+4. Verify expected elements appear with `browserWaitFor`
+5. Screenshot results for visual regression comparison
+6. Report pass/fail based on element presence and content
+
+### Build and Deploy Pipeline
+1. Pull latest code: `cliExecute("git pull origin master")`
+2. Install dependencies: `cliExecute("npm install")`
+3. Run tests: `cliExecute("npm test")`
+4. Build: `cliExecute("npm run build")`
+5. Check for errors in exit codes and stderr
+6. Deploy using cloud-deployment tools if build succeeds
+
+## HITL and Guardrail Overrides
+
+CLI executor commands are subject to HITL (human-in-the-loop) approval when the agent's security tier requires it. At **strict** and **paranoid** tiers, every `cliExecute` call goes through the configured HITL handler before running. At **balanced**, only commands matching destructive patterns (rm -rf, DROP TABLE, etc.) trigger approval.
+
+Even after HITL approval, **guardrail overrides** (enabled by default) perform a post-approval safety scan on the command. The code-safety guardrail can veto commands like `rm -rf /` or `sudo chmod 777` that a human or LLM judge might have approved accidentally.
+
+To use an LLM judge instead of a human for CLI approvals:
+```bash
+wunderland chat --llm-judge
+```
+
+See the **hitl-safety** skill for full HITL handler configuration.
+
+## Best Practices
+
+- **Least privilege** — use the most restrictive security tier that allows the needed operations
+- **No credential leaks** — never echo, print, or concatenate secret values into commands
+- **Idempotent commands** — prefer commands that can be safely re-run (mkdir -p, cp, rsync)
+- **Cleanup** — close browser sessions when done; terminate background processes that are no longer needed
+- **Error handling** — always check exit codes; parse stderr for diagnostic information
+- **Timeouts** — set appropriate timeouts; a hung command blocks the agent
+- **Dry run first** — for destructive operations (delete, overwrite), show the user what will happen before executing
+- **Working directory** — always specify absolute paths; never assume the current directory

package/registry/curated/voice-telephony/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: voice-telephony
+version: '1.0.0'
+description: Voice call routing with Twilio, Telnyx, and Plivo plus STT/TTS streaming providers — IVR setup, provider selection, and voice pipeline configuration.
+author: Wunderland
+namespace: wunderland
+category: voice
+tags: [voice, telephony, twilio, telnyx, plivo, stt, tts, ivr, call-routing, streaming]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\U0001F4DE"
+---
+
+# Voice & Telephony
+
+You are a voice pipeline specialist. You configure telephony providers for call routing, set up IVR flows, and wire STT/TTS streaming providers for real-time voice conversations.
+
+## Telephony Providers
+
+### Twilio
+- **Tool IDs**: `twilioVoiceCall`, `twilioVoiceProvider`
+- **Secrets**: `twilio.accountSid`, `twilio.authToken`
+- **Best for**: Most popular choice; rich ecosystem, global coverage, excellent docs
+- **Capabilities**:
+  - Outbound phone calls with TwiML scripting
+  - Inbound call webhook handling
+  - Notify mode (TTS message + hangup)
+  - Conversation mode (bidirectional media streams)
+  - HMAC-SHA1 webhook signature verification
+  - Call status callbacks
+  - E.164 phone number validation
+- **Pricing**: ~$0.013/min outbound US, ~$0.0085/min inbound US; phone numbers from $1/mo
+
+### Telnyx
+- **Tool IDs**: `telnyxVoiceCall`, `telnyxVoiceProvider`
+- **Secrets**: `telnyx.apiKey`, `telnyx.connectionId`
+- **Best for**: Cost-effective alternative to Twilio; private IP network for better quality
+- **Capabilities**:
+  - Outbound/inbound calls via Telnyx Call Control API
+  - WebSocket media streaming for real-time audio
+  - Programmable call flows (transfer, conference, record)
+  - Mission Control portal for configuration
+  - SIP trunking support
+- **Pricing**: ~$0.007/min outbound US (roughly half of Twilio); phone numbers from $1/mo
+
+### Plivo
+- **Tool IDs**: `plivoVoiceCall`, `plivoVoiceProvider`
+- **Secrets**: `plivo.authId`, `plivo.authToken`
+- **Best for**: High-volume call centers; simple API; good APAC/India coverage
+- **Capabilities**:
+  - Outbound/inbound calls with XML-based call flows
+  - Conference calling with moderation
+  - Call recording and transcription
+  - DTMF input handling
+  - Number masking for privacy
+- **Pricing**: ~$0.010/min outbound US; competitive international rates
+
+## STT (Speech-to-Text) Streaming Providers
+
+### Deepgram Streaming STT
+- **Extension**: `streaming-stt-deepgram`
+- **Secrets**: `deepgram.apiKey`
+- **Best for**: Fastest real-time transcription; best accuracy for conversational speech
+- **Features**:
+  - WebSocket streaming with <300ms latency
+  - Multiple models: Nova-2 (general), Enhanced (noisy), Base (fastest)
+  - Interim results for responsive UX
+  - Punctuation, diarization, smart formatting
+  - 30+ languages
+- **Recommendation**: Default choice for production voice apps
+
+### Whisper Streaming STT
+- **Extension**: `streaming-stt-whisper`
+- **Secrets**: `openai.apiKey` (for API) or none (for local)
+- **Best for**: Self-hosted/local deployment; highest accuracy for non-English languages
+- **Features**:
+  - OpenAI Whisper model (local or API)
+  - Chunk-based streaming (not true real-time, ~1-2s chunks)
+  - 97+ languages with strong multilingual performance
+  - Local mode: no API costs, requires GPU for real-time
+- **Recommendation**: Use when Deepgram is unavailable or for local/offline deployments
+
+### Google Cloud STT
+- **Extension**: `google-cloud-stt`
+- **Secrets**: `google.serviceAccountJson`
+- **Best for**: Enterprise Google Cloud integration; medical/legal domain models
+- **Features**:
+  - Streaming recognition via gRPC
+  - Multiple models: default, phone_call, video, medical_conversation
+  - Speaker diarization (who said what)
+  - Word-level confidence and timing
+  - Automatic punctuation
+
+### Vosk (Offline)
+- **Extension**: `vosk`
+- **Secrets**: None
+- **Best for**: Fully offline/airgapped deployments; edge devices
+- **Features**:
+  - Local models, no internet required
+  - Lightweight enough for Raspberry Pi
+  - 20+ language models available
+  - Speaker identification
+- **Recommendation**: Use for privacy-critical or offline scenarios
+
+## TTS (Text-to-Speech) Streaming Providers
+
+### ElevenLabs Streaming TTS
+- **Extension**: `streaming-tts-elevenlabs`
+- **Secrets**: `elevenlabs.apiKey`
+- **Best for**: Most natural-sounding voices; voice cloning; emotional expression
+- **Features**:
+  - WebSocket streaming with ~200ms time-to-first-byte
+  - 30+ pre-built voices, custom voice cloning
+  - Adjustable stability, similarity, style
+  - 29 languages with accent control
+  - SSML support
+- **Recommendation**: Default choice for the best voice quality
+
+### OpenAI Streaming TTS
+- **Extension**: `streaming-tts-openai`
+- **Secrets**: `openai.apiKey`
+- **Best for**: Simple integration; consistent quality; bundled with OpenAI key
+- **Features**:
+  - 6 voices (alloy, echo, fable, onyx, nova, shimmer)
+  - Real-time streaming
+  - Speed adjustment (0.25x to 4.0x)
+  - HD quality option
+- **Recommendation**: Use when already using OpenAI for LLM; quality is good but fewer customization options
+
+### Amazon Polly
+- **Extension**: `amazon-polly`
+- **Secrets**: `aws.accessKeyId`, `aws.secretAccessKey`
+- **Best for**: AWS ecosystem; SSML control; Neural and Standard voices
+- **Features**:
+  - Neural voices (natural) and Standard voices (cheaper)
+  - Full SSML support (pauses, emphasis, phonemes)
+  - 60+ voices across 30+ languages
+  - Newscaster and Conversational styles
+- **Recommendation**: Use for AWS-native deployments or when SSML control is critical
+
+### Google Cloud TTS
+- **Extension**: `google-cloud-tts`
+- **Secrets**: `google.serviceAccountJson`
+- **Best for**: Google Cloud integration; WaveNet voices; Studio voices
+- **Features**:
+  - WaveNet voices (very natural), Standard, Neural2, and Studio
+  - SSML support with audio effects
+  - 50+ languages, 380+ voices
+  - Audio profiles (telephony, headphone, smart speaker)
+
+### Piper (Offline)
+- **Extension**: `piper`
+- **Secrets**: None
+- **Best for**: Offline/local TTS; edge deployment; no API costs
+- **Features**:
+  - ONNX-based, runs entirely local
+  - 100+ voices across 30+ languages
+  - Fast inference on CPU
+  - Configurable quality levels
+- **Recommendation**: Use for offline deployments or when API costs are a concern
+
+## Voice Pipeline Architecture
+
+A complete voice pipeline connects these components:
+
+```
+Microphone → VAD → STT Provider → LLM → TTS Provider → Speaker
+                                    ↑
+                              Memory/Context
+```
+
+### Pipeline Components
+1. **VAD (Voice Activity Detection)** — `openwakeword` or `porcupine` for wake word, built-in adaptive VAD for speech detection
+2. **STT** — converts speech to text in real-time
+3. **LLM** — processes the transcribed text and generates a response
+4. **TTS** — converts the LLM response back to speech
+5. **Audio Transport** — WebRTC, WebSocket, or telephony media stream
+
+### Provider Selection Guide
+
+| Requirement | STT Pick | TTS Pick |
+|-------------|----------|----------|
+| Best quality | Deepgram Nova-2 | ElevenLabs |
+| Lowest latency | Deepgram | ElevenLabs or OpenAI |
+| Cheapest | Vosk (free) | Piper (free) |
+| Offline capable | Vosk | Piper |
+| Multilingual | Whisper | Google Cloud TTS |
+| Enterprise/compliance | Google Cloud STT | Amazon Polly |
+| Simplest setup | Deepgram | OpenAI TTS |
+
+### IVR (Interactive Voice Response) Setup
+1. Provision a phone number from Twilio, Telnyx, or Plivo
+2. Configure inbound webhook URL pointing to your AgentOS endpoint
+3. Wire the voice pipeline: STT → LLM → TTS
+4. Define call flow states: greeting, menu, transfer, voicemail
+5. Handle DTMF input for numeric menu selections
+6. Set fallback to human operator for unhandled cases
+7. Enable call recording for quality assurance (with consent disclosure)
+
+## Best Practices
+
+- **Latency budget** — total round-trip (STT + LLM + TTS) should be under 2 seconds for natural conversation
+- **Interruption handling** — enable barge-in so users can interrupt the TTS playback
+- **Fallback chain** — if primary STT/TTS fails, fall back to a secondary provider
+- **Cost management** — use Vosk/Piper for development/testing; paid providers for production
+- **Audio quality** — use 16kHz 16-bit mono PCM for telephony; 44.1kHz for high-fidelity
+- **Silence detection** — configure VAD sensitivity to avoid cutting off slow speakers
+- **Regional compliance** — recording laws vary by jurisdiction; always disclose when recording