From f30f57bfabc2d64bd280e28fe5949a2bdf0e958c Mon Sep 17 00:00:00 2001 From: Alix-007 <267018309+Alix-007@users.noreply.github.com> Date: Wed, 25 Mar 2026 18:28:04 +0800 Subject: [PATCH 1/2] docs: add cron job behavior guide --- README.md | 3 + docs/cron.md | 125 ++++++++++++++++++++++++++++++++++++ docs/tools_configuration.md | 5 +- 3 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 docs/cron.md diff --git a/README.md b/README.md index f627e261e..15aa13ab3 100644 --- a/README.md +++ b/README.md @@ -550,6 +550,8 @@ PicoClaw supports scheduled reminders and recurring tasks through the `cron` too * **Recurring tasks**: "Remind me every 2 hours" -> triggers every 2 hours * **Cron expressions**: "Remind me at 9am daily" -> uses cron expression +See [docs/cron.md](docs/cron.md) for current schedule types, execution modes, command-job gates, and persistence details. + ## 📚 Documentation For detailed guides beyond this README: @@ -559,6 +561,7 @@ For detailed guides beyond this README: | [Docker & Quick Start](docs/docker.md) | Docker Compose setup, Launcher/Agent modes | | [Chat Apps](docs/chat-apps.md) | All 17+ channel setup guides | | [Configuration](docs/configuration.md) | Environment variables, workspace layout, security sandbox | +| [Scheduled Tasks and Cron Jobs](docs/cron.md) | Cron schedule types, deliver modes, command gates, job storage | | [Providers & Models](docs/providers.md) | 30+ LLM providers, model routing, model_list configuration | | [Spawn & Async Tasks](docs/spawn-tasks.md) | Quick tasks, long tasks with spawn, async sub-agent orchestration | | [Hooks](docs/hooks/README.md) | Event-driven hook system: observers, interceptors, approval hooks | diff --git a/docs/cron.md b/docs/cron.md new file mode 100644 index 000000000..2ce888df9 --- /dev/null +++ b/docs/cron.md @@ -0,0 +1,125 @@ +# Scheduled Tasks and Cron Jobs + +> Back to [README](../README.md) + +PicoClaw stores scheduled jobs in the current workspace and can run them either as reminders, full agent turns, or shell commands. + +## Schedule Types + +PicoClaw currently uses three schedule forms in the cron tool: + +- `at_seconds`: one-time job, relative to now. After it runs, the job is removed from the store. +- `every_seconds`: recurring interval, in seconds. +- `cron_expr`: recurring cron expression such as `0 9 * * *`. + +The CLI command `picoclaw cron add` currently supports recurring jobs only: + +- `--every ` +- `--cron ''` + +There is no CLI flag for a one-time `at` job today. + +Examples: + +```bash +picoclaw cron add --name "Daily summary" --message "Summarize today's logs" --cron "0 18 * * *" +picoclaw cron add --name "Ping" --message "heartbeat" --every 300 --deliver +``` + +## Execution Modes + +Jobs are stored with a message payload and can execute in three stable user-facing modes: + +### `deliver: false` + +This is the default for the cron tool. + +When the job fires, PicoClaw sends the saved message back through the agent loop as a new agent turn. Use this for scheduled work that may need reasoning, tools, or a generated reply. + +### `deliver: true` + +When the job fires, PicoClaw publishes the saved message directly to the target channel and recipient without agent processing. + +The CLI `picoclaw cron add --deliver` flag uses this mode. + +### `command` + +When a cron-tool job includes `command`, PicoClaw runs that shell command through the `exec` tool and publishes the command output back to the channel. + +For command jobs, `deliver` is forced to `false` when the job is created. The saved `message` becomes descriptive text only; the scheduled action is the shell command. + +The current CLI `picoclaw cron add` command does not expose a `command` flag. + +## Config and Security Gates + +### `tools.cron` + +`tools.cron.enabled` controls whether the agent-facing `cron` tool is registered. Default: `true`. + +If you disable `tools.cron`, users can no longer create or manage jobs through the agent tool. The gateway still starts the cron service and the CLI still uses the same job store, so keep `tools.cron.enabled` on if you expect scheduled agent-turn or command jobs to execute through the gateway. + +`tools.cron.exec_timeout_minutes` sets the timeout used for scheduled command execution. Default: `5`. Set `0` for no timeout. + +### `tools.exec` + +Scheduled command jobs depend on `tools.exec.enabled`. Default: `true`. + +If `tools.exec.enabled` is `false`: + +- new command jobs are rejected by the cron tool +- existing command jobs publish a `command execution is disabled` error when they fire + +`tools.exec.allow_remote` is still enforced by the exec tool, but cron command scheduling already requires an internal channel when the job is created. In practice, reminder jobs can be scheduled from remote channels, while scheduled command jobs are limited to internal channels. + +### `allow_command` + +`tools.cron.allow_command` defaults to `true`. + +This is not a hard disable switch. If you set `allow_command` to `false`, PicoClaw still allows a command job when the caller explicitly passes `command_confirm: true`. + +Command jobs also require an internal channel. Non-command reminders do not have that restriction. + +Example: + +```json +{ + "tools": { + "cron": { + "enabled": true, + "exec_timeout_minutes": 5, + "allow_command": true + }, + "exec": { + "enabled": true + } + } +} +``` + +## Persistence and Location + +Cron jobs are stored in: + +```text +/cron/jobs.json +``` + +By default, the workspace is: + +```text +~/.picoclaw/workspace +``` + +If `PICOCLAW_HOME` is set, the default workspace becomes: + +```text +$PICOCLAW_HOME/workspace +``` + +Both the gateway and `picoclaw cron` CLI subcommands use the same `cron/jobs.json` file. + +Notes: + +- one-time `at_seconds` jobs are deleted after they run +- recurring jobs stay in the store until removed +- disabled jobs stay in the store and still appear in `picoclaw cron list` diff --git a/docs/tools_configuration.md b/docs/tools_configuration.md index b5907b991..3380a0a67 100644 --- a/docs/tools_configuration.md +++ b/docs/tools_configuration.md @@ -226,8 +226,11 @@ The cron tool is used for scheduling periodic tasks. | Config | Type | Default | Description | |------------------------|------|---------|------------------------------------------------| +| `enabled` | bool | true | Register the agent-facing cron tool | +| `allow_command` | bool | true | Allow command jobs without extra confirmation | | `exec_timeout_minutes` | int | 5 | Execution timeout in minutes, 0 means no limit | -| `allow_command` | bool | false | Allow cron tasks to execute shell commands | + +For schedule types, execution modes (`deliver`, agent turn, and command jobs), persistence, and the current command-security gates, see [Scheduled Tasks and Cron Jobs](cron.md). ## MCP Tool From 59babde0cf99610817eda0cbaa55d3d2b24bcb33 Mon Sep 17 00:00:00 2001 From: Alix-007 <267018309+Alix-007@users.noreply.github.com> Date: Wed, 25 Mar 2026 18:34:20 +0800 Subject: [PATCH 2/2] docs: clarify cron disabled execution behavior --- docs/cron.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cron.md b/docs/cron.md index 2ce888df9..6483fa137 100644 --- a/docs/cron.md +++ b/docs/cron.md @@ -56,7 +56,7 @@ The current CLI `picoclaw cron add` command does not expose a `command` flag. `tools.cron.enabled` controls whether the agent-facing `cron` tool is registered. Default: `true`. -If you disable `tools.cron`, users can no longer create or manage jobs through the agent tool. The gateway still starts the cron service and the CLI still uses the same job store, so keep `tools.cron.enabled` on if you expect scheduled agent-turn or command jobs to execute through the gateway. +If you disable `tools.cron`, users can no longer create or manage jobs through the agent tool. The gateway still starts `CronService`, but it does not install the job execution callback. As a result, due jobs do not actually run; one-time jobs may be deleted and recurring jobs may be rescheduled without executing their payload. The CLI still uses the same job store. `tools.cron.exec_timeout_minutes` sets the timeout used for scheduled command execution. Default: `5`. Set `0` for no timeout.