concinno-skills-mobile

Mobile / telephony agent skills for Concinno. Unified on the MIT-licensed Twilio Python SDK — the most mature programmatic-telephony provider for SMS, voice, and WhatsApp Business. Device-side Android / iOS shell control is intentionally out of scope; that belongs to the Sancio runtime layer.

Why this package exists

HammerBench (and adjacent benchmarks) evaluate agents on realistic telephony / SaaS workflows. Concinno can drive Twilio today over plain HTTPS — no device emulator, no OS-level hook — making this the blue-ocean entry point for mobile skills in the Concinno ecosystem.

Status

MVP (0.1.0) — three one-shot tools:

Microsoft Teams / push-only providers (Pushover, ntfy) are deferred until they land in a dedicated sibling sub-package.

Install

pip install concinno-skills-mobile

twilio>=9.0 is a hard dependency and is pulled in automatically.

Twilio account requirements

You need a Twilio account (trial or paid). Outbound SMS / WhatsApp messages and voice calls cost money per Twilio's per-country pricing. A WARNING-level log line is emitted to stderr before every outbound call so the billing risk is visible in agent traces.

• SMS: buy (or port) a Twilio phone number in a country you need to send to; long-code numbers are rate-limited to roughly 1 msg/sec.
• WhatsApp: register a WhatsApp-enabled sender (Twilio Sandbox for trials or a fully-verified Business sender for production) — addresses use the whatsapp:+<digits> prefix on both to and from_.
• Voice: any Twilio number with Voice capability works; the call behaviour is driven by either inline TwiML XML or a URL pointing at a hosted TwiML document.

Credentials

The Twilio account_sid + auth_token are read from the Concinno CredentialStore, which consults (in order):

1. Process runtime overrides via CredentialStore.set(...).
2. Env var CONCINNO_CRED_<UPPER_KEY>.
3. ~/.concinno/credentials.json.

Example ~/.concinno/credentials.json:

{
  "twilio_account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "twilio_auth_token":  "your_auth_token_here"
}

If either credential is missing the tool returns {"error": "no twilio credentials — set account_sid + auth_token via CredentialStore / env"} rather than crashing.

Phone number formats

All destination / sender numbers are validated locally before the network call, both to catch typos early and to avoid burning billable round-trips on malformed input:

• SMS / Voice: E.164 only (+<country_code><digits>, max 15 digits).
• WhatsApp: whatsapp:+<country_code><digits>.

Both sides of every send / call are validated with the same rule.

Usage via Concinno ToolRegistry

When the consumer sets CONCINNO_LOAD_PLUGINS=1, the default registry auto-mounts every mobile tool:

import os
os.environ["CONCINNO_LOAD_PLUGINS"] = "1"

from concinno.tools.registry import get_default_registry

reg = get_default_registry()
assert {"TwilioSms", "TwilioWhatsApp", "TwilioVoiceCall"} <= set(
    reg.list_deferred()
)

sms = reg.get("TwilioSms")
sms.call(
    action="send",
    to="+14155551234",
    from_="+14155550000",
    body="Hello from Concinno",
)

Direct Python usage

from concinno_skills_mobile import (
    TwilioSms,
    TwilioWhatsApp,
    TwilioVoiceCall,
)

TwilioSms().call(
    action="send",
    to="+14155551234",
    from_="+14155550000",
    body="hi",
)

TwilioWhatsApp().call(
    action="send",
    to="whatsapp:+14155551234",
    from_="whatsapp:+14155550000",
    body="hi",
)

TwilioVoiceCall().call(
    action="create",
    to="+14155551234",
    from_="+14155550000",
    twiml="<Response><Say>Hi from Concinno</Say></Response>",
)

All tools return {"ok": True, ...} on success or {"error": "..."} on failure — same shape as other Concinno built-in tools. No exceptions escape the call() surface.

Concurrency

All three tools set is_concurrency_safe = False. Twilio rate limits (per-from-number for SMS; per-subaccount for voice; per-sender for WhatsApp) make serial dispatch the sane default; Concinno's scheduler will honour this automatically.

License

Apache-2.0. See LICENSE in the Concinno monorepo.