62 lines
3.2 KiB
Markdown
62 lines
3.2 KiB
Markdown
---
|
||
summary: "Design notes for a direct `clawdis agent` CLI subcommand without WhatsApp delivery"
|
||
read_when:
|
||
- Adding or modifying the agent CLI entrypoint
|
||
---
|
||
# Plan: `clawdis agent` (direct-to-agent invocation)
|
||
|
||
Goal: Add a CLI subcommand that talks directly to the configured agent command (no WhatsApp send), while reusing the same session handling and config clawdis already uses for auto-replies.
|
||
|
||
## Why
|
||
- Sometimes we want to poke the agent directly (same prompt templates/sessions) without sending a WhatsApp message.
|
||
- Current flows (`send`, gateway, directives) always route through WhatsApp or add wrapping text; we need a clean “talk to agent now” tool.
|
||
|
||
## Behavior
|
||
- Command: `clawdis agent`
|
||
- Required: `--message <text>`
|
||
- Session selection:
|
||
- If `--session-id` given, use it.
|
||
- Else if `--to <e164>` given, derive session key like auto-reply (`per-sender`, same normalization) and load/create session id from `session store` path in config.
|
||
- Else error (“need --to or --session-id”).
|
||
- Runs the same external command as auto-reply: `inbound.reply.command` from config (honors `reply.session` options: sendSystemOnce, sendSystemOnce=false, typing, timeouts, etc.).
|
||
- Uses the same templating rules for Body as command mode, but **skips** WhatsApp-specific wrappers (group intro, media hints). Keep session intro/bodyPrefix if sendSystemOnce is false, otherwise follow session config.
|
||
- Thinking/verbose:
|
||
- Accept flags `--thinking <off|minimal|low|medium|high>` and `--verbose <on|off>`.
|
||
- Persist into session store (like directive-only flow) and inject into the command invocation.
|
||
- Output:
|
||
- Default: print the agent’s text reply to stdout.
|
||
- `--json` flag: print full payload (text, any media URL, timing).
|
||
- Does **not** send anything to WhatsApp; purely local agent run.
|
||
|
||
## Flags (proposed)
|
||
- `--message, -m <text>` (required)
|
||
- `--to, -t <e164>` (derive session)
|
||
- `--session-id <uuid>` (override)
|
||
- `--thinking <off|minimal|low|medium|high>`
|
||
- `--verbose <on|off>`
|
||
- `--json` (structured output)
|
||
- `--timeout <sec>` (override command timeout)
|
||
|
||
## Implementation steps
|
||
1) CLI:
|
||
- Add subcommand in `src/cli/program.ts`.
|
||
- Wire options, setVerbose, createDefaultDeps.
|
||
2) Command handler (new file `src/commands/agent.ts`):
|
||
- Load config.
|
||
- Resolve session store + session id (reuse `deriveSessionKey`, `loadSessionStore`, `saveSessionStore`).
|
||
- Apply thinking/verbose overrides and persist to session entry.
|
||
- Build command body (no WhatsApp wrappers; honor sessionIntro/bodyPrefix as per config).
|
||
- Call `runCommandWithTimeout` (same as auto-reply) and parse response (reuse splitter for MEDIA, etc.).
|
||
- Return text (and mediaUrl) to stdout / JSON.
|
||
3) Share logic:
|
||
- Extract helper(s) from `auto-reply/reply.ts` if needed (session + thinking persistence) to avoid duplication.
|
||
4) Tests:
|
||
- Unit tests for handler: session creation, thinking persistence, resume with `--session-id`, JSON output.
|
||
- Snapshot of command args to ensure no WhatsApp wrappers.
|
||
5) Docs:
|
||
- Add usage examples to CLI help and README.
|
||
|
||
## Out of scope (for now)
|
||
- Chat directives `/cmd` in WhatsApp. (Can reuse the same handler later.)
|
||
- Media input/attachments. Start text-only; extend later if needed.
|