The underscore prefix convention signals an unused parameter, but it's
now actively used by the sender allowlist logic.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: atomic claim prevents scheduled tasks from executing twice (#138)
Replace the two-phase getDueTasks() + deferred updateTaskAfterRun() with
an atomic SQLite transaction (claimDueTasks) that advances next_run
BEFORE dispatching tasks to the queue. This eliminates the race window
where subsequent scheduler polls re-discover in-progress tasks.
Key changes:
- claimDueTasks(): SELECT + UPDATE in a single db.transaction(), so no
poll can read stale next_run values. Once-tasks get next_run=NULL;
recurring tasks get next_run advanced to the future.
- computeNextRun(): anchors interval tasks to the scheduled time (not
Date.now()) to prevent cumulative drift. Includes a while-loop to
skip missed intervals and a guard against invalid interval values.
- updateTaskAfterRun(): simplified to only record last_run/last_result
since next_run is already handled by the claim.
Closes#138, #211, #300, #578
Co-authored-by: @taslim (PR #601)
Co-authored-by: @baijunjie (Issue #138)
Co-authored-by: @Michaelliv (Issue #300)
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* style: apply prettier formatting
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: track running task ID in GroupQueue to prevent duplicate execution (#138)
Previous commits implemented an "atomic claim" approach (claimDueTasks)
that advanced next_run before execution. Per Gavriel's review, this
solved the symptom at the wrong layer and introduced crash-recovery
risks for once-tasks.
This commit reverts claimDueTasks and instead fixes the actual bug:
GroupQueue.enqueueTask() only checked pendingTasks for duplicates, but
running tasks had already been shifted out. Adding runningTaskId to
GroupState closes that gap with a 3-line fix at the correct layer.
The computeNextRun() drift fix is retained, applied post-execution
where it belongs.
Closes#138, #211, #300, #578
Co-authored-by: @taslim (PR #601)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add changelog entry for scheduler duplicate fix
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add contributors for scheduler race condition fix
Co-Authored-By: Taslim <9999802+taslim@users.noreply.github.com>
Co-Authored-By: BaiJunjie <7956480+baijunjie@users.noreply.github.com>
Co-Authored-By: Michael <13676242+Michaelliv@users.noreply.github.com>
Co-Authored-By: Kyle Zhike Chen <3477852+kk17@users.noreply.github.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: gavrielc <gabicohen22@yahoo.com>
Co-authored-by: Taslim <9999802+taslim@users.noreply.github.com>
Co-authored-by: BaiJunjie <7956480+baijunjie@users.noreply.github.com>
Co-authored-by: Michael <13676242+Michaelliv@users.noreply.github.com>
Co-authored-by: Kyle Zhike Chen <3477852+kk17@users.noreply.github.com>
* refactor: implement channel architecture and dynamic setup
- Introduced ChannelRegistry for dynamic channel loading
- Decoupled WhatsApp from core index.ts and config.ts
- Updated setup wizard to support ENABLED_CHANNELS selection
- Refactored IPC and group registration to be channel-aware
- Verified with 359 passing tests and clean typecheck
* style: fix formatting in config.ts to pass CI
* refactor(setup): full platform-agnostic transformation
- Harmonized all instructional text and help prompts
- Implemented conditional guards for WhatsApp-specific steps
- Normalized CLI terminology across all 4 initial channels
- Unified troubleshooting and verification logic
- Verified 369 tests pass with clean typecheck
* feat(skills): transform WhatsApp into a pluggable skill
- Created .claude/skills/add-whatsapp with full 5-phase interactive setup
- Fixed TS7006 'implicit any' error in IpcDeps
- Added auto-creation of STORE_DIR to prevent crashes on fresh installs
- Verified with 369 passing tests and clean typecheck
* refactor(skills): move WhatsApp from core to pluggable skill
- Move src/channels/whatsapp.ts to add-whatsapp skill add/ folder
- Move src/channels/whatsapp.test.ts to skill add/ folder
- Move src/whatsapp-auth.ts to skill add/ folder
- Create modify/ for barrel file (src/channels/index.ts)
- Create tests/ with skill package validation test
- Update manifest with adds/modifies lists
- Remove WhatsApp deps from core package.json (now skill-managed)
- Remove WhatsApp-specific ghost language from types.ts
- Update SKILL.md to reflect skill-apply workflow
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(skills): move setup/whatsapp-auth.ts into WhatsApp skill
The WhatsApp auth setup step is channel-specific — move it from core
to the add-whatsapp skill so core stays minimal.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(skills): convert Telegram skill to pluggable channel pattern
Replace the old direct-integration approach (modifying src/index.ts,
src/config.ts, src/routing.test.ts) with self-registration via the
channel registry, matching the WhatsApp skill pattern.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(skills): fix add-whatsapp build failure and improve auth flow
- Add missing @types/qrcode-terminal to manifest npm_dependencies
(build failed after skill apply without it)
- Make QR-browser the recommended auth method (terminal QR too small,
pairing codes expire too fast)
- Remove "replace vs alongside" question — channels are additive
- Add pairing code retry guidance and QR-browser fallback
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: remove hardcoded WhatsApp default and stale Baileys comment
- ENABLED_CHANNELS now defaults to empty (fresh installs must configure
channels explicitly via /setup; existing installs already have .env)
- Remove Baileys-specific comment from storeMessageDirect() in db.ts
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(skills): convert Discord, Slack, Gmail skills to pluggable channel pattern
All channel skills now use the same self-registration pattern:
- registerChannel() factory at module load time
- Barrel file append (src/channels/index.ts) instead of orchestrator modifications
- No more *_ONLY flags (DISCORD_ONLY, SLACK_ONLY) — use ENABLED_CHANNELS instead
- Removed ~2500 lines of old modify/ files (src/index.ts, src/config.ts, src/routing.test.ts)
Gmail retains its container-runner.ts and agent-runner modifications (MCP
mount + server config) since those are independent of channel wiring.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: use getRegisteredChannels instead of ENABLED_CHANNELS
Remove the ENABLED_CHANNELS env var entirely. The orchestrator now
iterates getRegisteredChannelNames() from the channel registry —
channels self-register via barrel imports and their factories return
null when credentials are missing, so unconfigured channels are
skipped automatically.
Deleted setup/channels.ts (and its tests) since its sole purpose was
writing ENABLED_CHANNELS to .env. Refactored verify, groups, and
environment setup steps to detect channels by credential presence
instead of reading ENABLED_CHANNELS.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add breaking change notice and whatsapp migration instructions
CHANGELOG.md documents the pluggable channel architecture shift and
provides migration steps for existing WhatsApp users.
CLAUDE.md updated: Quick Context reflects multi-channel architecture,
Key Files lists registry.ts instead of whatsapp.ts, and a new
Troubleshooting section directs users to /add-whatsapp if WhatsApp
stops connecting after upgrade.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: rewrite READMEs for pluggable multi-channel architecture
Reflects the architectural shift from a hardcoded WhatsApp bot to a
pluggable channel platform. Adds upgrading notice, Mermaid architecture
diagram, CI/License/TypeScript/PRs badges, and clarifies that slash
commands run inside the Claude Code CLI.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: move pluggable channel architecture details to SPEC.md
Revert READMEs to original tone with only two targeted changes:
- Add upgrading notice for WhatsApp breaking change
- Mention pluggable channels in "What It Supports"
Move Mermaid diagram, channel registry internals, factory pattern
explanation, and self-registration walkthrough into docs/SPEC.md.
Update stale WhatsApp-specific references in SPEC.md to be
channel-agnostic.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: move upgrading notice to CHANGELOG, add changelog link
Remove the "Upgrading from Pre-Pluggable Versions" section from
README.md — breaking change details belong in the CHANGELOG. Add a
Changelog section linking to CHANGELOG.md.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: expand CHANGELOG with full PR #500 changes
Cover all changes: channel registry, WhatsApp moved to skill, removed
core dependencies, all 5 skills simplified, orchestrator refactored,
setup decoupled. Use Claude Code CLI instructions for migration.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: bump version to 1.2.0 for pluggable channel architecture
Minor version bump — new functionality (pluggable channels) with a
managed migration path for existing WhatsApp users. Update version
references in CHANGELOG and update skill.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Fix skill application
* fix: use slotted barrel file to prevent channel merge conflicts
Pre-allocate a named comment slot for each channel in
src/channels/index.ts, separated by blank lines. Each skill's
modify file only touches its own slot, so three-way merges
never conflict when applying multiple channels.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: resolve real chat ID during setup for token-based channels
Instead of registering with `pending@telegram` (which never matches
incoming messages), the setup skill now runs an inline bot that waits
for the user to send /chatid, capturing the real chat ID before
registration.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: setup delegates to channel skills, fix group sync and Discord metadata
- Restructure setup SKILL.md to delegate channel setup to individual
channel skills (/add-whatsapp, /add-telegram, etc.) instead of
reimplementing auth/registration inline with broken placeholder JIDs
- Move channel selection to step 5 where it's immediately acted on
- Fix setup/groups.ts: write sync script to temp file instead of passing
via node -e which broke on shell escaping of newlines
- Fix Discord onChatMetadata missing channel and isGroup parameters
- Add .tmp-* to .gitignore for temp sync script cleanup
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: align add-whatsapp skill with main setup patterns
Add headless detection for auth method selection, structured inline
error handling, dedicated number DM flow, and reorder questions to
match main's trigger-first flow.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: add missing auth script to package.json
The add-whatsapp skill adds src/whatsapp-auth.ts but doesn't add
the corresponding npm script. Setup and SKILL.md reference `npm run auth`
for WhatsApp QR terminal authentication.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: update Discord skill tests to match onChatMetadata signature
The onChatMetadata callback now takes 5 arguments (jid, timestamp,
name, channel, isGroup) but the Discord skill tests only expected 3.
This caused skill application to roll back on test failure.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: replace 'pluggable' jargon with clearer language
User-facing text now says "multi-channel" or describes what it does.
Developer-facing text uses "self-registering" or "channel registry".
Also removes extra badge row from README.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: align Chinese README with English version
Remove extra badges, replace pluggable jargon, remove upgrade section
(now in CHANGELOG), add missing intro line and changelog section,
fix setup FAQ answer.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: warn on installed-but-unconfigured channels instead of silent skip
Channels with missing credentials now emit WARN logs naming the exact
missing variable, so misconfigurations surface instead of being hidden.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: simplify changelog to one-liner with compare link
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add isMain flag and channel-prefixed group folders
Replace MAIN_GROUP_FOLDER constant with explicit isMain boolean on
RegisteredGroup. Group folders now use channel prefix convention
(e.g., whatsapp_main, telegram_family-chat) to prevent cross-channel
collisions.
- Add isMain to RegisteredGroup type and SQLite schema (with migration)
- Replace all folder-based main group checks with group.isMain
- Add --is-main flag to setup/register.ts
- Strip isMain from IPC payload (defense in depth)
- Update MCP tool description for channel-prefixed naming
- Update all channel SKILL.md files and documentation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: gavrielc <gabicohen22@yahoo.com>
Co-authored-by: Koshkoshinski <daniel.milliner@gmail.com>
* fix: shadow .env file in container to prevent agents from reading secrets
The main agent's container mounts the project root read-only, which
inadvertently exposed the .env file containing API keys. Mount /dev/null
over /workspace/project/.env to shadow it — secrets are already passed
via stdin and never need to be read from disk inside the container.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: adapt .env shadowing and runtime for Apple Container
Apple Container (VirtioFS) only supports directory mounts, not file
mounts. The previous /dev/null host-side mount over .env crashes with
VZErrorDomain "A directory sharing device configuration is invalid".
- Dockerfile: entrypoint now shadows .env via mount --bind inside the
container, then drops privileges via setpriv to the host UID/GID
- container-runner: main containers skip --user and pass RUN_UID/RUN_GID
env vars so entrypoint starts as root for mount --bind
- container-runtime: switch to Apple Container CLI (container), fix
cleanupOrphans to use container list --format json
- Skill: add Dockerfile and container-runner.ts to
convert-to-apple-container skill (v1.1.0)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: revert src to Docker runtime, keep Apple Container in skill only
The source files should remain Docker-compatible. The Apple Container
adaptations live in the convert-to-apple-container skill and are applied
on demand.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
WhatsApp wraps certain message types in container objects:
- viewOnceMessageV2 (listen-once voice, view-once media)
- ephemeralMessage (disappearing messages)
- editedMessage (edited messages)
Without calling Baileys' normalizeMessageContent(), the fields
conversation, extendedTextMessage, imageMessage, etc. are nested
inside the wrapper and invisible to our direct field access. This
causes these messages to be silently dropped with no error.
- Import and call normalizeMessageContent() early in messages.upsert
- Use the normalized content object for all field reads
- Add mock to test suite
Co-authored-by: Ethan M <ethan@nanoclaw.local>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
- Support ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN for custom API endpoints
- Add documentation for third-party/open-source model usage
Co-authored-by: wenglixin <wenglixin@menusifu.cn>
* fix(db): remove unique constraint on folder to support multi-channel agents
* ci: implement automated skill drift detection and self-healing PRs
* fix: align registration logic with Gavriel's feedback and fix build/test issues from Daniel Mi
* style: conform to prettier standards for CI validation
* test: fix branch naming inconsistency in CI (master vs main)
* fix(ci): robust module resolution by removing file extensions in scripts
* refactor(ci): simplify skill validation by removing redundant combination tests
* style: conform skills-engine to prettier, unify logging in index.ts and cleanup unused imports
* refactor: extract multi-channel DB changes to separate branch
Move channel column, folder suffix logic, and related migrations
to feat/multi-channel-db-v2 for independent review. This PR now
contains only CI/CD optimizations, Prettier formatting, and
logging improvements.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
The fetchLatestWaWebVersion call added in #443 could crash the
connection flow if the HTTP fetch fails. Wrap with .catch() to log
and fall back to the default Baileys version.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Baileys' default WhatsApp version can fall behind when WhatsApp updates
their protocol, causing 405 "Method Not Allowed" errors on the websocket
handshake. This prevents both new authentication and reconnection.
Now fetches the latest version on each connection so it stays current.
Applied to both the runtime connection (whatsapp.ts) and the setup auth
flow (whatsapp-auth.ts).
- Replace 'as any' with proper type definition for error status code access
- Add error logging to sendPresenceUpdate() catch block
- Add debug logging when .env file is not found
These changes improve type safety and visibility into potential failures
without changing any core functionality.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: gavrielc <gabicohen22@yahoo.com>
* fix: filter empty messages from polling queries
WhatsApp history sync writes empty protocol artifacts (delivery receipts,
status updates) to the database. On fresh installs, the main channel
(no trigger required) picks these up and spawns a container agent
unnecessarily, causing a message loop on first startup.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: update test to match empty-content filtering in queries
The getMessagesSince query now filters out empty messages, so the test
should expect 0 results instead of 1.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Containers had no TZ set, so any time-aware code inside ran in UTC while
the host interpreted bare timestamps as local time. Now TIMEZONE from
config.ts is passed via -e TZ= to the container args.
Also rejects Z-suffixed or offset-suffixed timestamps in the container's
schedule_task validation, since bare timestamps are expected to be local
time and silently accepting UTC suffixes would cause an offset mismatch.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
The container agent-runner had 'Andy' hardcoded as the sender name in
archived conversation transcripts. This ignored the configurable
ASSISTANT_NAME setting, so users who changed their assistant's name
(via .env or config) would still see 'Andy' in transcripts.
- Add assistantName field to ContainerInput interface (both host and
container copies)
- Pass ASSISTANT_NAME from config through to container in index.ts
and task-scheduler.ts
- Thread assistantName through createPreCompactHook and
formatTranscriptMarkdown in the agent-runner
- Use 'AssistantNameMissing' as fallback instead of 'Andy' so a
missing name is visible rather than silently wrong
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The main group's project root was mounted read-write, allowing the
container agent to modify host application code (e.g. dist/container-runner.js)
to inject arbitrary mounts on next restart — a full sandbox escape.
Fix: mount the project root read-only. Writable paths the agent needs
(group folder, IPC, .claude/) are already mounted separately. The
agent-runner source is now copied into a per-group writable location
so agents can still customize container-side behavior without affecting
host code or other groups.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Setup scripts are standalone CLI tools run via tsx with no runtime
imports from the main app. Moving them out of src/ excludes them from
the tsc build output and reduces the compiled bundle size.
- git mv src/setup/ setup/
- Fix imports to use ../src/logger.js and ../src/config.js
- Update package.json, vitest.config.ts, SKILL.md references
- Fix platform tests to be cross-platform (macOS + Linux)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: migrate setup from bash scripts to cross-platform Node.js modules
Replace 9 bash scripts + qr-auth.html with a two-phase setup system:
a bash bootstrap (setup.sh) for Node.js/npm verification, and TypeScript
modules (src/setup/) for everything else. Resolves cross-platform issues:
sed -i replaced with fs operations, sqlite3 CLI replaced with better-sqlite3,
browser opening made cross-platform, service management supports launchd/
systemd/WSL nohup fallback, SQL injection prevented with parameterized queries.
Add Linux systemctl equivalents alongside macOS launchctl commands in 8 skill
files and CLAUDE.md.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: setup migration issues — pairing code, systemd fallback, nohup escaping
- Emit WhatsApp pairing code immediately when received, before polling
for auth completion. Previously the code was only shown in the final
status block after auth succeeded — a catch-22 since the user needs
the code to authenticate. (whatsapp-auth.ts)
- Add systemd user session pre-check before attempting to write the
user-level service unit. Falls back to nohup wrapper when user-level
systemd is unavailable (e.g. su session without login/D-Bus). (service.ts)
- Rewrite nohup wrapper template using array join instead of template
literal to fix shell variable escaping (\\$ → $). (service.ts)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: detect stale docker group and kill
orphaned processes on Linux systemd
* fix: remove redundant shell option from execSync to fix TS2769
execSync already runs in a shell by default; the explicit `shell: true`
caused a type error with @types/node which expects string, not boolean.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: hide QR browser auth option on headless Linux
Emit IS_HEADLESS from environment step and condition SKILL.md to
only show pairing code + QR terminal when no display server is
available (headless Linux without WSL). WSL is excluded from the
headless gate because browser opening works via Windows interop.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Several async calls in the message loop and group queue are
fire-and-forget without .catch() handlers. When WhatsApp disconnects
or containers fail unexpectedly, these produce unhandled rejections
that can crash the process.
Add explicit .catch() at each call site so errors are logged with
full context (groupJid, taskId) instead of crashing:
- channel.setTyping() in message loop (adapted for channel abstraction)
- startMessageLoop() in main()
- runForGroup() and runTask() in group-queue (5 call sites)
Closes#221
Co-authored-by: Naveen Jain <1779929+naveenspark@users.noreply.github.com>
Co-authored-by: Skip Potter <skip.potter.va@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
The test expected voice notes (audioMessage with no caption) to be
delivered with empty content, but 6f177ad added a guard that skips
messages with no text content. Update assertion accordingly.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The HOME_DIR fallback '/Users/user' is macOS-specific and incorrect.
Use os.homedir() from Node's os module which works cross-platform
and returns the actual home directory from /etc/passwd on Linux.
Co-authored-by: Cursor <cursoragent@cursor.com>
The original notifyIdle condition (!result.result) never fired in
streaming input mode because every result has non-null text content.
This caused due tasks to wait up to 30 minutes for the idle timer.
- Call notifyIdle for ALL successful results (not just null ones)
- Add isTaskContainer flag so user messages queue instead of being
forwarded to task containers (which blocked notifyIdle from the
message container's onOutput path)
- Reset idleWaiting in sendMessage so containers aren't preempted
while actively working on a new incoming message
- Replace 30-min IDLE_TIMEOUT with 10s close timer for task containers
since they are single-turn and should exit promptly after their result
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Containers that finish work but stay alive in waitForIpcMessage() block
queued scheduled tasks. Previous approaches killed active containers
mid-work. This fix tracks idle state via the session-update marker
(status: success, result: null) and only preempts when the container
is idle-waiting, not actively working.
Closes#293
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
WhatsApp protocol messages (encryption key distribution, read receipts,
ephemeral settings, senderKeyDistributionMessage) have a message envelope
but no text content. These were being stored in messages.db and processed
by the agent, causing:
1. Agent responds to empty messages, wasting API tokens
2. Container stays alive indefinitely (idle timer resets)
3. Scheduled tasks blocked (queue slot occupied)
This fix skips messages with empty content before calling onMessage,
preventing protocol messages from being stored and processed.
Fixes#250
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
copyFileSync crashes with EISDIR when a skill contains subdirectories
like scripts/. Skills support nested folders (scripts/, examples/,
templates/) per the Claude Code spec. Use fs.cpSync to handle the
complete skill structure.
* Fix trigger pattern tests to use config name
Tests hardcoded "Andy" but the pattern is built from
`ASSISTANT_NAME` which comes from `.env`.
---
Generated with the help of Claude Code, https://claude.ai/code
Co-Authored-By: Claude Code Opus 4.6 <noreply@anthropic.com>
* Restore usage comment in trim test
---
Generated with the help of Claude Code, https://claude.ai/code
Co-Authored-By: Claude Code Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Code Opus 4.6 <noreply@anthropic.com>
Move all container-runtime-specific logic (binary name, mount args,
stop command, startup check, orphan cleanup) into a single file so
swapping runtimes only requires replacing this one file.
Neutralize "Apple Container" references in comments and docs that
would become incorrect after a runtime swap. References that list
both runtimes as options are left unchanged.
No behavior change — Apple Container remains the default runtime.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: multi-channel infrastructure with explicit channel/is_group tracking
- Add channels[] array and findChannel() routing in index.ts, replacing
hardcoded whatsapp.* calls with channel-agnostic callbacks
- Add channel TEXT and is_group INTEGER columns to chats table with
COALESCE upsert to protect existing values from null overwrites
- is_group defaults to 0 (safe: unknown chats excluded from groups)
- WhatsApp passes explicit channel='whatsapp' and isGroup to onChatMetadata
- getAvailableGroups filters on is_group instead of JID pattern matching
- findChannel logs warnings instead of silently dropping unroutable JIDs
- Migration backfills channel/is_group from JID patterns for existing DBs
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: skills engine v0.1 — deterministic skill packages with rerere resolution
Three-way merge engine for applying skill packages on top of a core
codebase. Skills declare which files they add/modify, and the engine
uses git merge-file for conflict detection with git rerere for
automatic resolution of previously-seen conflicts.
Key components:
- apply: three-way merge with backup/rollback safety net
- replay: clean-slate replay for uninstall and rebase
- update: core version updates with deletion detection
- rebase: bake applied skills into base (one-way)
- manifest: validation with path traversal protection
- resolution-cache: pre-computed rerere resolutions
- structured: npm deps, env vars, docker-compose merging
- CI: per-skill test matrix with conflict detection
151 unit tests covering merge, rerere, backup, replay, uninstall,
update, rebase, structured ops, and edge cases.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add Discord and Telegram skill packages
Skill packages for adding Discord and Telegram channels to NanoClaw.
Each package includes:
- Channel implementation (add/src/channels/)
- Three-way merge targets for index.ts, config.ts, routing.test.ts
- Intent docs explaining merge invariants
- Standalone integration tests
- manifest.yaml with dependency/conflict declarations
Applied via: npx tsx scripts/apply-skill.ts .claude/skills/add-discord
These are inert until applied — no runtime impact.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* remove unused docs (skills-system-status, implementation-guide)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* fix: WA 515 stream error reconnect exiting early before key sync
Pass isReconnect flag on 515 reconnect so the registered-creds check
doesn't bail out before the handshake completes (caused "logging in..."
hang after successful pairing).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: container permission errors on Docker with non-default uid
Make /home/node world-writable in the Dockerfile so the SDK can write
.claude.json. Add --user flag matching host uid/gid in container-runner
so bind-mounted files are accessible. Skip when running as root (uid 0),
as the container's node user (uid 1000), or on native Windows.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: write ASSISTANT_NAME to .env during setup
When a custom assistant name is chosen, persist it to .env so config.ts
picks it up at runtime. Uses temp file for cross-platform sed
compatibility (macOS/Linux/WSL).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Replace inline SKILL.md instructions with executable shell scripts
for each setup phase (environment check, deps, container, auth,
groups, channels, mounts, service, verify). Scripts emit structured
status blocks for reliable parsing.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add is_bot_message column and support dedicated phone numbers
Replace fragile content-prefix bot detection with an explicit
is_bot_message database column. The old prefix check (content NOT LIKE
'Andy:%') is kept as a backstop for pre-migration messages.
- Add is_bot_message column with automatic backfill migration
- Add ASSISTANT_HAS_OWN_NUMBER env var to skip name prefix when the
assistant has its own WhatsApp number
- Move prefix logic into WhatsApp channel (no longer a router concern)
- Remove prefixAssistantName from Channel interface
- Load .env via dotenv so launchd-managed processes pick up config
- WhatsApp bot detection: fromMe for own number, prefix match for shared
Based on #160 and #173.
Co-Authored-By: Stefan Gasser <stefan@stefangasser.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: extract shared .env parser and remove dotenv dependency
Extract .env parsing into src/env.ts, used by both config.ts and
container-runner.ts. Reads only requested keys without loading secrets
into process.env, avoiding leaking API keys to child processes.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Stefan Gasser <stefan@stefangasser.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Two issues fixed:
- Use 'paused' instead of 'available' to stop typing. Baileys'
sendPresenceUpdate('available') sends a global <presence> stanza and
ignores the JID, so chatstate never left 'composing' and WhatsApp
suppressed duplicate composing notifications per XEP-0085.
- Add setTyping call when piping messages to an already-running
container. Previously only the first message (which spawns a new
container) triggered the typing indicator.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Added missing Browsers mock to the Baileys vi.mock and made
triggerMessages async to flush microtasks before assertions.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sending 'paused' after the first response caused WhatsApp to stop
relaying subsequent 'composing' presence updates. Using 'available'
keeps the bot in a state where typing indicators work consistently.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Without announcing 'available' after connecting, WhatsApp stops relaying
composing/paused presence updates after the first message.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Use a PreToolUse SDK hook to prepend `unset ANTHROPIC_API_KEY
CLAUDE_CODE_OAUTH_TOKEN` to every Bash command Kit runs, preventing
secret leakage via env/printenv/echo/$PROC. Secrets are now passed
via stdin JSON instead of mounted env files, closing all known
exfiltration vectors.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
- IPC register_group handler now passes requiresTrigger field to registerGroup(),
fixing groups silently defaulting to trigger-required mode
- Agent runner scans /workspace/extra/* and passes them as additionalDirectories
to the SDK query, so CLAUDE.md files in mounted dirs are loaded automatically
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add pairing code auth with 515 reconnect handling (Baileys stream
error after pairing is now retried instead of failing)
- Use Browsers.macOS('Chrome') identifier for WhatsApp compatibility
- Fix LID-to-phone translation for DMs using signalRepository.getPNForLID
- Strip device suffix (:0) from resolved phone JIDs
- Update setup skill with three auth options (browser QR, pairing code,
terminal QR), DM channel type, and LID troubleshooting
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Container timeout and idle timeout both fire at 30min, racing the
graceful shutdown. The hard kill returns error status, rolling back
the message cursor even though output was already sent — causing
duplicate messages indefinitely.
- Grace period: hard timeout is now IDLE_TIMEOUT + 30s minimum
- Timeout after output resolves as success (idle cleanup, not failure)
- Don't roll back cursor if output was already sent to user
- Remove src/telegram.ts and config vars (added to PR #156 by mistake)
- Add typecheck step to CI workflow
- Add container-runner timeout behavior tests
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add Telegram channel with agent swarm support
Add Telegram as a messaging channel that can run alongside WhatsApp
or standalone (TELEGRAM_ONLY mode). Includes bot pool support for
agent swarms where each subagent appears as a different bot identity
in the group.
- Add grammy dependency for Telegram Bot API
- Route messages through tg: JID prefix convention
- Add storeMessageDirect for non-Baileys channels
- Add sender field to IPC send_message for swarm identity
- Support TELEGRAM_BOT_TOKEN, TELEGRAM_ONLY, TELEGRAM_BOT_POOL config
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add index.ts refactor plan
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: extract channel abstraction, IPC, and router from index.ts
Break the 1088-line monolith into focused modules:
- src/channels/whatsapp.ts: WhatsAppChannel class implementing Channel interface
- src/ipc.ts: IPC watcher and task processing with dependency injection
- src/router.ts: message formatting, outbound routing, channel lookup
- src/types.ts: Channel interface, OnInboundMessage, OnChatMetadata types
Also adds regression test suite (98 tests), updates all documentation
and skill files to reflect the new architecture.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* ci: add test workflow for PRs
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: remove accidentally committed pool-bot assets
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(ci): remove grammy from base dependencies
Grammy is installed by the /add-telegram skill, not a base dependency.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Enable CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 and
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 in container env so
agents use Claude Code's built-in persistent memory instead of
manually editing CLAUDE.md. Remove instructions that told agents to
write context into CLAUDE.md files.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: streaming container mode, IPC messaging, agent teams support
Major architectural shift from single-shot container runs to long-lived
streaming containers with IPC-based message injection.
- Agent runner: query loop with AsyncIterable prompt to keep stdin open
for agent teams (fixes isSingleUserTurn premature shutdown)
- New standalone stdio MCP server (ipc-mcp-stdio.ts) inheritable by
subagents, with send_message and schedule_task tools
- Streaming output: parse OUTPUT_START/END markers in real-time, send
results to WhatsApp as they arrive
- IPC file-based messaging: host writes to ipc/{group}/input/, agent
polls for follow-up messages without respawning containers
- Per-group settings.json with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
- SDK bumped to 0.2.34 for TeamCreate tool support
- Container idle timeout (30min) with _close sentinel for shutdown
- Orphaned container cleanup on startup
- alwaysRespond flag for groups that skip trigger pattern check
- Uncaught exception/rejection handlers with timestamps in logger
- Combined SDK documentation into single deep dive reference
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: remove unused ipc-mcp.ts (replaced by ipc-mcp-stdio.ts)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: clarify agent communication model in docs and tool descriptions
- CLAUDE.md (main + global): split communication instructions into
"responding to messages" vs "scheduled tasks" sections
- send_message tool: note that scheduled task output is not sent to user
- Remove structured output (outputFormat) — not needed with current flow
- Regular output is sent to WhatsApp; scheduled task output is only logged
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: ignore dynamic group data while preserving base structure
Only track groups/main/CLAUDE.md and groups/global/CLAUDE.md. All other
group directories and files are ignored to prevent tracking user-specific
session data.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: resolve critical bugs in streaming container mode
Bug 1 (scheduled task hang): Task scheduler now passes onOutput callback
with idle timer that writes _close sentinel after IDLE_TIMEOUT, so
containers exit cleanly instead of blocking queue slots for 30 minutes.
Scheduled tasks stay alive for interactive follow-up via IPC.
Bug 2 (timeout disabled): Remove resetTimeout() from stderr handler.
SDK writes debug logs continuously, resetting the timer on every line.
Timeout now only resets on actual output markers in stdout.
Bug 3 (trigger bypass): Piped messages in startMessageLoop now check
trigger pattern for non-main groups. Non-trigger messages accumulate in
DB and are pulled as context via getMessagesSince when a trigger arrives.
Bug 7 (non-atomic IPC writes): GroupQueue.sendMessage uses temp file +
rename for atomic writes, matching ipc-mcp-stdio.ts pattern.
Also: flip isVerbose back to false (debug leftover), add isScheduledTask
to host-side ContainerInput interface.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: idle timer not starting + scheduled task groupFolder missing
Two bugs that prevented the scheduled task idle timeout fix from working:
1. onOutput was only called when parsed.result !== null, but session
update markers have result: null. The idle timer never started for
"silent" query completions, leaving containers parked at
waitForIpcMessage until hard timeout.
2. Scheduler's onProcess callback didn't pass groupFolder to
queue.registerProcess, so closeStdin no-oped (groupFolder was null).
The _close sentinel was never written even when the idle timer fired.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: duplicate messages and timestamp rollback in piping path
Two bugs introduced by the trigger context accumulation change:
1. processGroupMessages didn't advance lastAgentTimestamp until after
the container finished. The piping path's getMessagesSince(lastAgent
Timestamp) re-fetched messages already sent as the initial prompt,
causing duplicates.
2. processGroupMessages overwrote lastAgentTimestamp with the original
batch timestamp on completion, rolling back any advancement made by
the piping path while the container was running.
Fix: advance lastAgentTimestamp immediately after building the prompt,
before starting the container. This matches the piping path behavior
and eliminates both the overlap and the rollback.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: container idles 30 extra minutes after _close during query
When _close was detected during pollIpcDuringQuery, it was consumed
(deleted) and stream.end() was called. But after runQuery returned,
main() still emitted a session-update marker (resetting the host's idle
timer) and called waitForIpcMessage (which polled forever since _close
was already gone). The container had to wait for a second _close.
Fix: runQuery now returns closedDuringQuery. When true, main() skips
the session-update marker and waitForIpcMessage, exiting immediately.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: resume branching, internal tags, and output forwarding
- Fix resume branching: pass resumeSessionAt with last assistant UUID
to anchor each query loop resume to the correct conversation tree
position. Prevents agent responses landing on invisible branches
when agent teams subagents create parallel JSONL entries.
- Add <internal> tag stripping: agent can wrap internal reasoning in
<internal> tags which are logged but not sent to WhatsApp. Prevents
duplicate messages and internal monologue reaching users.
- Forward scheduled task output: scheduled tasks now send result text
to WhatsApp (with <internal> stripping), matching regular message
behavior. No more special-case instructions.
- Update Communication guidance in CLAUDE.md: simplified to "your
output is sent to the user or group" with soft guidance on
<internal> tags and send_message usage.
- Add messaging behavior docs to schedule_task tool: prompts the
scheduling agent to include guidance on whether the task should
always/conditionally/never message the user.
- Mount security: containerPath now optional, defaults to basename
of hostPath.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: cursor rollback on error, flush guard, verbose logging
- Roll back lastAgentTimestamp on container error so retries can
re-process the messages instead of silently losing them.
- Add guard flag to flushOutgoingQueue to prevent duplicate sends
from concurrent flushes during rapid WA reconnects.
- Revert isVerbose from hardcoded false back to env-based check
(LOG_LEVEL=debug|trace).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: orphan container cleanup was silently failing
The startup cleanup used `container ls --format {{.Names}}` which is
Docker Go-template syntax. Apple Container only supports `--format json`
or `--format table`. The command errored with exit code 64, but the
catch block silently swallowed it — orphan containers were never cleaned
up on restart.
Fixed to use `--format json` and parse `configuration.id` from the
JSON output. Also filters by `status: running` and logs a warning on
failure instead of silently catching.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add Discord badge and community section
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: idle timer reset on null results and flush queue message loss
- Only reset idle timer on actual results (non-null), not session-update
markers. Prevents containers staying alive 30 extra minutes after the
agent finishes work.
- flushOutgoingQueue now uses shift() instead of splice(0) so unattempted
messages stay in the queue if an unexpected error bails the loop.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add Agent Swarms to README
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: update Telegram skill for current architecture
Rewrite integration instructions to match the per-group queue/SQLite
architecture: remove onMessage callback pattern (store to DB, let
message loop pick up), fix startSchedulerLoop signature, add
TELEGRAM_ONLY service startup, SQLite registration, data/env/env sync,
@mention-to-trigger translation, and BotFather group privacy docs.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: Telegram skill message chunking, media placeholders, chat discovery
- Split long messages at Telegram's 4096 char limit to prevent silent
send failures
- Store placeholder text for non-text messages (photos, voice, stickers,
etc.) so the agent knows media was sent
- Update getAvailableGroups filter to include tg: chats so the agent can
discover and register Telegram chats via IPC
- Fix removal step numbering
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: update REQUIREMENTS.md and SPEC.md for SQLite architecture
- Replace all registered_groups.json / sessions.json / router_state.json
references with SQLite equivalents
- Fix CONTAINER_TIMEOUT default (300000 → 1800000)
- Add missing config exports (IDLE_TIMEOUT, MAX_CONCURRENT_CONTAINERS)
- Update folder structure: add missing src files (logger, group-queue,
mount-security), remove non-existent utils.ts, list all skills
- Fix agent-runner entry (ipc-mcp.ts → ipc-mcp-stdio.ts)
- Update startup sequence to reflect per-group queue architecture
- Fix env mounting description (data/env/env, not extracted vars)
- Update troubleshooting to use sqlite3 commands
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: fix README architecture description, revert SPEC.md env error
- README: update architecture blurb to mention per-group queue, add
group-queue.ts to key files, update file descriptions
- SPEC.md: restore correct credential filtering description (only auth
vars are extracted from .env, not the full file)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Setup skill fixes:
- Run QR auth in foreground with long timeout, not background
- Replace fragile message-based registration with DB group sync lookup
- Personal chats: ask for phone number instead of querying empty DB
- Consolidate trigger word + security model + channel selection into one step
- Remove `timeout` shell command (unavailable on macOS), use Bash tool timeout
- Query 40 groups, display 10 at a time, support name lookup
requiresTrigger support:
- Add requiresTrigger field to RegisteredGroup type and DB schema
- Skip trigger check when requiresTrigger is false (for solo/personal chats)
- Main group still always processes all messages (unchanged)
Agent-browser visibility:
- Append global CLAUDE.md to non-main agent system prompts via SDK
- Add browser tool docs to global and main CLAUDE.md
- Update skill description to be broader (not just "web testing")
- Reference agent-browser.md in root CLAUDE.md key files
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Always log detailed input/output/stderr on error (not just in verbose
mode), and stop truncating stderr/stdout in structured log fields.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
