zafiro-skill-whatsapp 0.1.0

WhatsApp skill package extracted from ia_orchestrator core

zafiro-skill-whatsapp

Autonomous WhatsApp skill package for the Zafiro orchestrator ecosystem.

This package is designed to run as an external skill pack with no direct imports from core app.* modules or other skill packages.

Documentation map

• Core integration guide: docs/CORE_INTEGRATION.md
• Full tools contract: docs/TOOLS_REFERENCE.md
• Skill manifest/prompt: skills/whatsapp.md

What this package contains

• Skill manifest: skills/whatsapp.md
• Skill entry-point registrar: zafiro_skill_whatsapp.extensions.skills.whatsapp:register_whatsapp_skill
• Tool entry-point registrar: zafiro_skill_whatsapp.extensions.tools.whatsapp_tools:register_whatsapp_tools
• WhatsApp adapter split by domain (runtime_ops, message_ops, contacts_ops, sync_ops)
• Policy tools (outbound allowlist and inbound auto-reply controls)
• CLI helpers for /wa-style commands
• Local integration layer (zafiro_skill_whatsapp.integrations) with optional host hooks

Adapter layout

adapters/whatsapp/
├── __init__.py               # public facade + centralized legacy module aliases
├── __main__.py               # package launcher entrypoint
├── runtime_ops/              # runtime lifecycle/state/config/types
├── message_ops/              # inbound/outbound/processing/auto-reply/queue
├── contacts_ops/             # directory/discovery/policy
└── sync_ops/                 # history/contacts/all-sync orchestration

Backward compatibility: legacy imports like adapters.whatsapp.contacts, adapters.whatsapp.outbound, adapters.whatsapp.state, etc. are exposed by central alias registration in adapters/whatsapp/__init__.py.

Runtime note:

• The old flat runtime modules (config, state, connection, types) were moved to runtime_ops/.
• Legacy import paths remain available through centralized aliasing in adapters/whatsapp/__init__.py.

Local-only artifacts

Keep local execution artifacts out of git (logs, data, media, plan exports). For plan files generated during local experimentation, use:

• local_runtime/plans_created/

This package .gitignore excludes these folders by default:

• logs/
• data/
• media/
• local_runtime/
• plans_created/

Install

From repository root:

./venv/bin/python -m pip install -e packages/whatsapp_skill

Console Testing Script

There is now a standalone console tester for this package:

Quick shortcut from repo root (recommended):

./packages/whatsapp_skill/scripts/wa.sh tools
./packages/whatsapp_skill/scripts/wa.sh tool wa_policy
./packages/whatsapp_skill/scripts/wa.sh tool save_whatsapp_contact "Gerald|50577427779|true|owner"
./packages/whatsapp_skill/scripts/wa.sh wa "status"
./packages/whatsapp_skill/scripts/wa.sh wa "sync"
./packages/whatsapp_skill/scripts/wa.sh wa "sync Zafiro"
./packages/whatsapp_skill/scripts/wa.sh wa "sync Zafiro 50 12 8"
./packages/whatsapp_skill/scripts/wa.sh repl

Direct python entrypoint (equivalent):

python packages/whatsapp_skill/scripts/wa_console.py list-tools
python packages/whatsapp_skill/scripts/wa_console.py run-tool wa_policy
python packages/whatsapp_skill/scripts/wa_console.py run-tool save_whatsapp_contact "Gerald|50577427779|true|owner"
python packages/whatsapp_skill/scripts/wa_console.py run-wa "status"
python packages/whatsapp_skill/scripts/wa_console.py run-wa "sync"
python packages/whatsapp_skill/scripts/wa_console.py run-wa "sync Zafiro"
python packages/whatsapp_skill/scripts/wa_console.py run-wa "sync Zafiro 50 12 8"
python packages/whatsapp_skill/scripts/wa_console.py repl

What it covers:

• run-tool: Executes any registered WhatsApp tool from this skill package.
• run-wa: Executes /wa admin subcommands (on, off, status, link, unlink, actor, etc.).
• repl: Interactive shell where you can test tool/admin commands quickly.

/wa sync UX (recommended):

• /wa sync: global adaptive sync validation.
• /wa sync <target> [limit] [max_rounds] [wait_seconds]: one-shot target sync + archive read.
• Compatibility aliases still available: sync auto, sync oneshot, sync os, sync all.

Skill and tools

Skill name: WhatsApp

Declared tools:

• save_whatsapp_contact
• save_whatsapp_contacts
• list_whatsapp_contacts
• save_whatsapp_group
• save_whatsapp_groups
• list_whatsapp_groups
• send_whatsapp
• read_whatsapp
• read_whatsapp_archive
• reply_whatsapp
• whatsapp_status
• whatsapp_recover
• wa_policy
• wa_set_autoreply (legacy compatibility)
• wa_allow_send
• wa_block_send
• wa_allow_reply
• wa_block_reply

See docs/TOOLS_REFERENCE.md for exact argument formats, examples, and output semantics for each tool.

Runtime model

• Standalone defaults live in zafiro_skill_whatsapp.integrations.
• Archive/history, contacts, groups and access-rules use ORM-backed tables created by this skill.
• Data is scoped by connected WhatsApp number (multi-account safe).
• If host ORM is configured (orm_session_factory or orm_engine_factory), tables are created/reused there.
• If host ORM is not configured, the skill logs a warning and falls back to local SQLite at WHATSAPP_LOCAL_DB_PATH.
• Optional host runtime hooks can be provided with configure_host_runtime(...) to bridge:
  • active-agent listing
  • task execution
  • effective-agent resolution
  • host ORM session/engine and storage account resolver

See docs/CORE_INTEGRATION.md for a full bootstrap example and deployment checklist.

Host integration contract

• Contract metadata API: get_host_runtime_contract().
• Contract validation API: validate_host_runtime_contract(...).
• Fail-fast API: assert_host_runtime_contract(...).

Expected hooks by mode:

• Core shared database mode (recommended):
  • required: orm_session_factory or orm_engine_factory
• Multi-account strict mode (recommended):
  • required: resolve_storage_account_key
• Optional:
  • storage_schema_initializer
  • get_active_agents, execute_task, resolve_effective_agent

Bootstrap order (recommended):

1. configure_host_runtime(...)
2. assert_host_runtime_contract(...)
3. Load entry points and register skills/tools

Dependency contract:

• Python dependencies are installed by package manager when this skill is added:
  • sqlalchemy, python-magic, neonize
• System dependency required by runtime:
  • libmagic (OS package; must be present on host image)

Entry points

pyproject.toml exports:

• zafiro.skills -> whatsapp
• zafiro.tools -> whatsapp

Key environment variables

• WHATSAPP_SESSION_NAME
• WHATSAPP_DEVICE_PLATFORM
• WHATSAPP_DEVICE_OS
• WHATSAPP_DEVICE_VERSION
• WHATSAPP_OUTBOX_DIR
• WHATSAPP_CONTACTS_PATH
• WHATSAPP_ACCESS_RULES_PATH
• WHATSAPP_MEDIA_DIR
• WHATSAPP_ACTIVE_ACCOUNT_PATH
• MESSAGE_ARCHIVE_PATH
• WHATSAPP_LOCAL_DB_PATH
• RECENT_SESSION_HISTORY_LIMIT
• WHATSAPP_FORWARD_URL
• WHATSAPP_FORWARD_SECRET
• WHATSAPP_SIMULATE_TYPING
• WHATSAPP_TYPING_MIN_MS
• WHATSAPP_TYPING_MAX_MS
• WHATSAPP_TYPING_MS_PER_CHAR
• WHATSAPP_SEND_AVAILABLE_PRESENCE
• WHATSAPP_AUTO_MARK_READ
• WHATSAPP_AUTO_REPLY_ENABLED

Validation checklist (current)

• No AST-level imports from app, zafiro_skill_hostal, or zafiro_skill_media
• Package imports succeed:
  • zafiro_skill_whatsapp
  • zafiro_skill_whatsapp.integrations
  • zafiro_skill_whatsapp.extensions.tools.whatsapp_tools
  • zafiro_skill_whatsapp.extensions.skills.whatsapp