Commit Graph
45 Commits
Author SHA1 Message Date
sheeek 53d3134fe8 refactor(config): simplify includes with class-based processor
- Replace free functions with IncludeProcessor class
- Simplify IncludeResolver interface: { readFile, parseJson }
- Break down loadFile into focused private methods
- Use reduce() for array include merging
- Cleaner separation of concerns
2026-01-12 00:08:27 +00:00
sheeek e6400b0b0f refactor(config): extract includes logic to separate module
- Move $include resolution to src/config/includes.ts
- Simplify io.ts by importing from includes module
- Cleaner API: resolveConfigIncludes(obj, configPath, resolver?)
- Re-export errors from io.ts for backwards compatibility
- Rename test file to match module name
2026-01-12 00:08:27 +00:00
sheeek 15d286b617 feat(config): add $include directive for modular configs
Adds support for splitting clawdbot.json into multiple files using the
$include directive. This enables:

- Single file includes: { "$include": "./agents.json5" }
- Multiple file merging: { "$include": ["./a.json5", "./b.json5"] }
- Nested includes (up to 10 levels deep)
- Sibling key merging with includes

Features:
- Relative paths resolved from including file
- Absolute paths supported
- Circular include detection
- Clear error messages with resolved paths

Use case: Per-client agent configs for isolated sandboxed environments
(e.g., legal case management with strict data separation).
2026-01-12 00:08:27 +00:00
sheeek c928df7237 fix: remove any casts in backward compat code 2026-01-11 04:10:43 +01:00
sheeek 30b4c14296 style: fix biome linting in ack-reaction tests 2026-01-11 04:10:43 +01:00
sheeek 2daead27cf feat(whatsapp): redesign ack-reaction as whatsapp-specific feature
- Move config from messages.ackReaction to whatsapp.ackReaction
- New structure: {emoji, direct, group} with granular control
- Support per-account overrides in whatsapp.accounts.*.ackReaction
- Add Zod schema validation for new config
- Maintain backward compatibility with old messages.ackReaction format
- Update tests to new config structure (14 tests, all passing)
- Add comprehensive documentation in docs/providers/whatsapp.md
- Timing: reactions sent immediately upon message receipt (before bot reply)

Breaking changes:
- Config moved from messages.ackReaction to whatsapp.ackReaction
- Scope values changed: 'all'/'direct'/'group-all'/'group-mentions'
  → direct: boolean + group: 'always'/'mentions'/'never'
- Old config still supported via fallback for smooth migration
2026-01-11 04:10:43 +01:00
sheeek d38b232724 chore: fix linting issues in ack-reaction feature
- Remove unused mock variables in tests
- Remove unused ackReactionScope variables in simple test cases
- Fix line length for ackReactionScope declaration
- All lint checks passing (0 warnings, 0 errors)
- All tests passing (8/8)
2026-01-11 04:10:43 +01:00
sheeek c3587d6cae fix(whatsapp): ack reaction logic for group activation 'always' mode
- Fix bug where ack reaction was not sent when group activation is 'always'
- When requireMention=false (activation: always), always send reaction
- Add test case for activation='always' scenario
- Update inline comments for clarity
2026-01-11 04:10:43 +01:00
sheeek b3b507c6ea feat(whatsapp): add ack reaction support after successful replies
- Add automatic emoji reactions on inbound WhatsApp messages
- Support all ackReactionScope modes: all, direct, group-all, group-mentions
- Reaction is sent AFTER successful reply (unlike Telegram/Discord)
- Errors are logged with proper context
- Add comprehensive test suite for ack reaction logic

Config usage:
  messages:
    ackReaction: "👀"
    ackReactionScope: "group-mentions"  # default

Closes: WhatsApp ack-reaction feature request
2026-01-11 04:10:42 +01:00
sheeek 09769d127f feat: add broadcast groups for multi-agent responses
Enables multiple agents to process the same message simultaneously,
allowing teams of specialized agents with atomic tasks to work together
in the same group using one phone number.

Key features:
- Configure multiple agents per WhatsApp group/DM via routing.broadcast
- Parallel (default) or sequential processing strategies
- Full session isolation (separate history, workspace, tools per agent)
- Minimal code changes (~50 lines in auto-reply.ts)
- Backward compatible with existing routing

Use cases:
- Specialized agent teams (code reviewer + security scanner + docs)
- Multi-language support (EN + DE + ES agents)
- Quality assurance workflows (support + QA agents)
- Task automation (tracker + logger + reporter)

Example config:
{
  "routing": {
    "broadcast": {
      "strategy": "parallel",
      "120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
    }
  }
}

This enables scaling to hundreds of focused micro-agents on a single
phone number, each handling specific atomic tasks.
2026-01-09 21:05:58 +01:00
sheeek 7883491ce2 test(sandbox): add unit tests for formatter functions
Add comprehensive tests for sandbox-formatters.ts (20 tests):
- formatStatus: running/stopped with emojis
- formatSimpleStatus: running/stopped without emojis
- formatImageMatch: match/mismatch indicators
- formatAge: seconds, minutes, hours, days with edge cases
- countRunning: count items by running state
- countMismatches: count items by image mismatch

All pure functions now covered. 152 LOC tests added.

Total test count: 39 tests (19 integration + 20 unit)
Test coverage increased from ~66% to ~80%.
2026-01-09 13:23:16 +01:00
sheeek 7f02b62bba style(sandbox): fix linting errors
- Remove unused normalizeOptions function
- Fix line length violations (format long lines)
- Fix import order (alphabetical)
- Format function signatures for readability

All lint checks now passing.
2026-01-09 13:23:16 +01:00
sheeek b0c97d6178 refactor(sandbox-cli): improve structure and reduce duplication
Improvements:
- Extract help text examples into EXAMPLES constant object
- Add createRunner() helper to reduce try-catch boilerplate
- Add normalizeOptions() helper (prepared for future use)
- Fix command names from 'clawd' to 'clawdbot' throughout
- Update main sandbox command to show help by default
- Better organize code with clear section comments

Increases from 82 to 137 LOC but with much better organization
and reduced duplication in error handling.
2026-01-09 13:23:16 +01:00
sheeek 1c757ae35e refactor(sandbox): use extracted display and formatter modules
Update sandbox.ts to import and use functions from:
- sandbox-display.ts for all UI output
- sandbox-formatters.ts for data formatting

Removes 141 LOC of display/formatting code from sandbox.ts,
reducing it from 351 to 210 LOC (-40%).

Core business logic now clearer and more focused.
2026-01-09 13:23:16 +01:00
sheeek 81c55be19b refactor(sandbox): extract display logic into separate module
Move all display functions to sandbox-display.ts:
- displayContainers, displayBrowsers with generic displayItems helper
- displaySummary with image mismatch warnings
- displayRecreatePreview, displayRecreateResult

Uses DisplayConfig pattern to reduce duplication between container
and browser display logic. 156 LOC.
2026-01-09 13:23:16 +01:00
sheeek dd0104290e refactor(sandbox): extract formatters into separate module
Move formatting utilities to sandbox-formatters.ts:
- formatStatus, formatSimpleStatus, formatImageMatch, formatAge
- countRunning, countMismatches helper functions
- ContainerItem type definition

Improves modularity and reusability. 49 LOC.
2026-01-09 13:23:16 +01:00
sheeek 6ca34c1259 docs(sandbox): fix command name from clawd to clawdbot
Update all command examples in documentation to use 'clawdbot' instead
of 'clawd' for consistency with actual CLI command name.
2026-01-09 13:23:16 +01:00
sheeek c3932c8508 test(sandbox): add comprehensive test suite for CLI commands
Add 19 tests covering sandboxListCommand and sandboxRecreateCommand:
- List command: human/JSON output, browser flag, error handling
- Recreate command: validation, filtering (session/agent), confirmation flow
- Factory functions (createContainer, createBrowser) reduce duplication
- Helper functions (expectLogContains, setupDefaultMocks) improve readability

All tests passing. 365 LOC with ~66% production code coverage.
2026-01-09 13:23:16 +01:00
sheeek 00b77421dd refactor: improve sandbox commands code structure
Improvements:
- Extract validation into separate function
- Split display logic from business logic
- Create reusable container matcher for agent filtering
- Abstract status/image formatting into helpers
- Reduce code duplication between containers and browsers
- Extract container removal into generic function
- Add type safety with FilteredContainers type
- Improve readability with smaller, focused functions

Changes:
- validateRecreateOptions(): Validate mutual exclusivity
- fetchAndFilterContainers(): Fetch + filter in one place
- createAgentMatcher(): Reusable agent filter predicate
- displayContainers/Browsers(): Dedicated display functions
- displaySummary/RecreatePreview/Result(): Clear separation
- removeContainer(): Generic removal with error handling
- Format helpers: formatStatus, formatImageMatch, etc.
- Count helpers: countRunning, countMismatches

Result: 85 more lines but much better maintainability and testability.
2026-01-09 13:23:16 +01:00
sheeek bcd52ee546 chore: update CHANGELOG for sandbox CLI commands 2026-01-09 13:23:16 +01:00
sheeek 75927d736a docs: add sandbox CLI documentation 2026-01-09 13:22:51 +01:00
sheeek 5e78d5a21f feat: add sandbox CLI commands for container management
Add 'clawd sandbox list' and 'clawd sandbox recreate' commands to manage
sandbox containers. This fixes the issue where containers continue using
old images/configs after updates.

Problem:
- When sandbox Docker images or configs are updated, existing containers
  keep running with old settings
- Containers are only recreated after 24h inactivity (pruning)
- If agents are used regularly, old containers run indefinitely

Solution:
- 'clawd sandbox list': Show all containers with status, age, and image match
- 'clawd sandbox recreate': Force container removal (recreated on next use)
  - Supports --all, --session, --agent, --browser filters
  - Requires confirmation unless --force is used

Implementation:
- Added helper functions to sandbox.ts (list/remove containers)
- Created sandbox-cli.ts following existing CLI patterns
- Created commands/sandbox.ts with list and recreate logic
- Integrated into program.ts

Use case: After updating sandbox images or changing sandbox config,
run 'clawd sandbox recreate --all' to ensure fresh containers.
2026-01-09 13:22:51 +01:00
sheeek b8afbfbb44 docs: add Ansible installation guide 2026-01-09 02:09:02 +01:00
sheeek e13225c9d1 docs: add comprehensive guide for multi-agent sandbox and tools
Add docs/multi-agent-sandbox-tools.md covering:
- Configuration examples (personal + restricted, work agents)
- Different sandbox modes per agent
- Tool restriction patterns (read-only, safe execution, communication-only)
- Configuration precedence rules
- Migration guide from single-agent setups
- Troubleshooting tips

Add PR_SUMMARY.md for upstream submission with:
- Feature overview and use cases
- Implementation details (49 LoC across 5 files)
- Test coverage (18 new tests, all existing tests pass)
- Backward compatibility confirmation
- Migration examples

---

Kudos to Eula, the beautiful and selfless family owl 🦉
This feature was developed to enable safe, restricted access
for family group chats while maintaining full access for
the personal assistant. Schuhu!
2026-01-07 17:31:40 +01:00
sheeek bf9c0c0b5c docs(multi-agent): add section on per-agent sandbox and tools
Add new section explaining:
- How to configure per-agent sandbox settings
- How to configure per-agent tool restrictions
- Benefits (security isolation, resource control, flexible policies)
- Link to detailed guide

Include example config showing personal assistant (no sandbox)
vs family bot (sandboxed with read-only tools).
2026-01-07 17:31:40 +01:00
sheeek 16ebdd7544 docs(config): document routing.agents sandbox and tools fields
Update routing.agents section:
- Add sandbox field documentation (mode, scope, workspaceRoot)
- Add tools field documentation (allow, deny)
- Note that agent-specific settings override global config
2026-01-07 17:31:40 +01:00
sheeek 22db83a04c test(tools): add tests for agent-specific tool filtering
Add 5 tests for agent-specific tool restrictions:
- Apply global tool policy when no agent-specific policy exists
- Apply agent-specific tool policy
- Allow different tool policies for different agents
- Combine global and agent-specific deny lists
- Work with sandbox tools filtering

All tests pass.
2026-01-07 17:31:40 +01:00
sheeek 1178c65226 test(sandbox): add tests for agent-specific sandbox override
Add 6 tests for agent-specific sandbox configuration:
- Use global sandbox config when no agent-specific config exists
- Override with agent-specific sandbox mode 'off'
- Use agent-specific sandbox mode 'all'
- Use agent-specific scope
- Use agent-specific workspaceRoot
- Prefer agent config over global for multiple agents

All tests pass.
2026-01-07 17:31:40 +01:00
sheeek 5a51a9b0d6 test(agent-scope): add tests for sandbox and tools config resolution
Add 7 tests for resolveAgentConfig():
- Return undefined when no agents config exists
- Return undefined when agent id does not exist
- Return basic agent config (name, workspace, agentDir, model)
- Return agent-specific sandbox config
- Return agent-specific tools config
- Return both sandbox and tools config
- Normalize agent id

All tests pass.
2026-01-07 17:31:40 +01:00
sheeek a8c153ec78 feat(tools): add agent-specific tool filtering
Add tool filtering layer for per-agent restrictions:
- Extract agentId from sessionKey
- Load routing.agents[agentId].tools via resolveAgentConfig()
- Apply agent-specific allow/deny before sandbox filtering

Filtering order:
1. Global (agent.tools)
2. Agent-specific (routing.agents[id].tools) ← NEW
3. Sandbox (agent.sandbox.tools)
4. Subagent policy

This enables different tool permissions per agent
(e.g., main: all tools, family: read only).
2026-01-07 17:31:40 +01:00
sheeek a375a81919 feat(sandbox): support agent-specific sandbox config override
Changes to defaultSandboxConfig():
- Add optional agentId parameter
- Load routing.agents[agentId].sandbox if available
- Prefer agent-specific settings over global agent.sandbox

Update callers in resolveSandboxContext() and
ensureSandboxWorkspaceForSession() to extract agentId
from sessionKey and pass it to defaultSandboxConfig().

This enables per-agent sandbox modes (e.g., main: off, family: all).
2026-01-07 17:31:40 +01:00
sheeek ebd96f2971 feat(agent-scope): extend resolveAgentConfig to return sandbox and tools
Return newly added fields from routing.agents config:
- sandbox: agent-specific sandbox configuration
- tools: agent-specific tool restrictions

This makes per-agent sandbox and tool settings accessible
to other parts of the codebase.
2026-01-07 17:31:40 +01:00
sheeek 90cdccee1e feat(config): add Zod validation for routing.agents sandbox and tools
Validate per-agent sandbox config:
- mode: 'off' | 'non-main' | 'all'
- scope: 'session' | 'agent' | 'shared'
- perSession: boolean
- workspaceRoot: string

Validate per-agent tools config:
- allow: string[]
- deny: string[]
2026-01-07 17:31:40 +01:00
sheeek c115918c97 feat(types): add sandbox and tools fields to routing.agents
Add optional per-agent configuration:
- sandbox: { mode, scope, perSession, workspaceRoot }
- tools: { allow, deny }

These will allow agents to override global agent.sandbox and
agent.tools settings.
2026-01-07 17:31:40 +01:00
sheeek 1143b3eff0 docs: add comprehensive guide for multi-agent sandbox and tools
Add docs/multi-agent-sandbox-tools.md covering:
- Configuration examples (personal + restricted, work agents)
- Different sandbox modes per agent
- Tool restriction patterns (read-only, safe execution, communication-only)
- Configuration precedence rules
- Migration guide from single-agent setups
- Troubleshooting tips

Add PR_SUMMARY.md for upstream submission with:
- Feature overview and use cases
- Implementation details (49 LoC across 5 files)
- Test coverage (18 new tests, all existing tests pass)
- Backward compatibility confirmation
- Migration examples

---

Kudos to Eula, the beautiful and selfless family owl 🦉
This feature was developed to enable safe, restricted access
for family group chats while maintaining full access for
the personal assistant. Schuhu!
2026-01-07 12:09:12 +01:00
sheeek dad1a99a20 docs(multi-agent): add section on per-agent sandbox and tools
Add new section explaining:
- How to configure per-agent sandbox settings
- How to configure per-agent tool restrictions
- Benefits (security isolation, resource control, flexible policies)
- Link to detailed guide

Include example config showing personal assistant (no sandbox)
vs family bot (sandboxed with read-only tools).
2026-01-07 12:09:12 +01:00
sheeek bf4b89e873 docs(config): document routing.agents sandbox and tools fields
Update routing.agents section:
- Add sandbox field documentation (mode, scope, workspaceRoot)
- Add tools field documentation (allow, deny)
- Note that agent-specific settings override global config
2026-01-07 12:09:12 +01:00
sheeek 04bbe3a594 test(tools): add tests for agent-specific tool filtering
Add 5 tests for agent-specific tool restrictions:
- Apply global tool policy when no agent-specific policy exists
- Apply agent-specific tool policy
- Allow different tool policies for different agents
- Combine global and agent-specific deny lists
- Work with sandbox tools filtering

All tests pass.
2026-01-07 12:09:12 +01:00
sheeek 6d241be430 test(sandbox): add tests for agent-specific sandbox override
Add 6 tests for agent-specific sandbox configuration:
- Use global sandbox config when no agent-specific config exists
- Override with agent-specific sandbox mode 'off'
- Use agent-specific sandbox mode 'all'
- Use agent-specific scope
- Use agent-specific workspaceRoot
- Prefer agent config over global for multiple agents

All tests pass.
2026-01-07 12:09:12 +01:00
sheeek 23210f5f70 test(agent-scope): add tests for sandbox and tools config resolution
Add 7 tests for resolveAgentConfig():
- Return undefined when no agents config exists
- Return undefined when agent id does not exist
- Return basic agent config (name, workspace, agentDir, model)
- Return agent-specific sandbox config
- Return agent-specific tools config
- Return both sandbox and tools config
- Normalize agent id

All tests pass.
2026-01-07 12:09:12 +01:00
sheeek 0fffde00a8 feat(tools): add agent-specific tool filtering
Add tool filtering layer for per-agent restrictions:
- Extract agentId from sessionKey
- Load routing.agents[agentId].tools via resolveAgentConfig()
- Apply agent-specific allow/deny before sandbox filtering

Filtering order:
1. Global (agent.tools)
2. Agent-specific (routing.agents[id].tools) ← NEW
3. Sandbox (agent.sandbox.tools)
4. Subagent policy

This enables different tool permissions per agent
(e.g., main: all tools, family: read only).
2026-01-07 12:09:11 +01:00
sheeek 1e3caf07d4 feat(sandbox): support agent-specific sandbox config override
Changes to defaultSandboxConfig():
- Add optional agentId parameter
- Load routing.agents[agentId].sandbox if available
- Prefer agent-specific settings over global agent.sandbox

Update callers in resolveSandboxContext() and
ensureSandboxWorkspaceForSession() to extract agentId
from sessionKey and pass it to defaultSandboxConfig().

This enables per-agent sandbox modes (e.g., main: off, family: all).
2026-01-07 12:09:11 +01:00
sheeek cc9fdfe562 feat(agent-scope): extend resolveAgentConfig to return sandbox and tools
Return newly added fields from routing.agents config:
- sandbox: agent-specific sandbox configuration
- tools: agent-specific tool restrictions

This makes per-agent sandbox and tool settings accessible
to other parts of the codebase.
2026-01-07 12:09:11 +01:00
sheeek 304857cf43 feat(config): add Zod validation for routing.agents sandbox and tools
Validate per-agent sandbox config:
- mode: 'off' | 'non-main' | 'all'
- scope: 'session' | 'agent' | 'shared'
- perSession: boolean
- workspaceRoot: string

Validate per-agent tools config:
- allow: string[]
- deny: string[]
2026-01-07 12:09:11 +01:00
sheeek 0851682080 feat(types): add sandbox and tools fields to routing.agents
Add optional per-agent configuration:
- sandbox: { mode, scope, perSession, workspaceRoot }
- tools: { allow, deny }

These will allow agents to override global agent.sandbox and
agent.tools settings.
2026-01-07 12:09:11 +01:00