Scheduling & SOP tools

This page documents the agent tools your Revka agent uses to schedule work and to drive Standard Operating Procedures (SOPs) from inside a session. There are two distinct families:

• The cron_* tools — cron_add, cron_list, cron_remove, cron_update, cron_run, and cron_runs — create and manage scheduled jobs, plus the older schedule tool kept for backward compatibility.
• The sop_* tools — sop_list, sop_execute, sop_advance, sop_approve, and sop_status — list and run SOPs and walk them through their approval gates.

Use this page when you need the exact parameters each tool accepts. For the operator-facing CLI equivalents see revka cron and revka skills, workflows & sop; for the conceptual model see Cron overview & expressions and SOP reference: syntax, triggers & execution. The same jobs and runs are reachable over HTTP — see Cron, sessions & attachments API.

Note

The scheduler that actually fires cron jobs runs inside the daemon, and most cron tools are blocked in read-only autonomy mode and when rate-limited. The whole subsystem also requires cron.enabled = true (the default) — when it is false, the cron tools and API return an error. See Autonomy levels & approvals.

Cron tools

A cron job has one of three schedule shapes and one of two job types the agent can create.

Schedule (the schedule field is oneOf):

Shape	JSON	Repeats?	Timezone-aware?
Cron expression	{"kind":"cron","expr":"0 9 * * 1-5","tz":"America/New_York"}	Yes	Yes (tz)
Interval	{"kind":"every","every_ms":3600000}	Yes	No
One-shot	{"kind":"at","at":"2026-12-31T23:59:00Z"}	No	No (always UTC)

• expr is a 5-, 6-, or 7-field cron expression. Standard 5-field crontab syntax is normalized internally (a seconds field is prepended and the weekday column is renumbered). Write the familiar 1 = Monday numbering.
• tz is an optional IANA timezone name and is honored only for cron schedules; at and every ignore it. Omitting tz defaults to UTC, not host-local time.
• every_ms must be a positive integer. at must be an RFC 3339 UTC datetime in the future.

Job types:

• shell — runs a command via sh -c. Validated against the security policy at creation and again at run time; medium-risk commands need approval. Requires command.
• agent — runs a prompt through the Revka agent with relevant memory context injected. Blocked in read-only mode. Requires prompt. (A third type, workflow, exists but is managed by workflow YAML triggers and cannot be created with these tools.)

cron_add

Creates a new shell or agent cron job. This is the preferred tool for scheduling agent-driven tasks and for sending scheduled messages to a channel.

{
  "name": "morning-brief",
  "schedule": {"kind": "cron", "expr": "0 9 * * 1-5", "tz": "America/New_York"},
  "job_type": "agent",
  "prompt": "Summarize overnight alerts and post to the channel",
  "delivery": {"mode": "announce", "channel": "discord", "to": "1234567890", "best_effort": true}
}

Field	Type	Meaning
schedule	object (required)	cron / at / every object. Tolerates being passed as a JSON-stringified object.
job_type	string	"shell" or "agent"; inferred as "agent" when only prompt is given.
command	string	Shell command — required for shell jobs.
prompt	string	Agent prompt — required for agent jobs.
name	string	Optional human-readable label.
session_target	string	"isolated" (default) or "main".
model	string	Model override for agent jobs.
allowed_tools	array	Tool names to whitelist for agent jobs; an empty array means all tools.
delivery	object	Routes job output to a chat channel after each run (see Delivery / announce mode).
delete_after_run	boolean	Defaults to true for at schedules.
approved	boolean	false by default; set true to approve a medium-risk shell command in supervised mode.

A minimal shell job:

{
  "schedule": {"kind": "cron", "expr": "*/5 * * * *"},
  "job_type": "shell",
  "command": "echo ok"
}

cron_list

Lists every registered job as a JSON array. Read-only; no security restrictions. Takes no parameters.

{}

Returns [] when there are no jobs. Errors if cron.enabled = false.

cron_remove

Permanently deletes a job by ID, along with its run history (the cron_runs rows cascade). Cannot be undone — to disable a job without deleting it, set enabled: false with cron_update instead.

{"job_id": "<uuid>"}

Field	Type	Meaning
job_id	string (required)	UUID returned by cron_add or cron_list.

Blocked in read-only mode and when rate-limited; errors if the job is not found.

cron_update

Patches one or more fields of an existing job. Only fields present in patch change; omitted fields keep their current values.

{
  "job_id": "<uuid>",
  "patch": {"enabled": false}
}

{
  "job_id": "<uuid>",
  "patch": {
    "schedule": {"kind": "cron", "expr": "0 10 * * *"},
    "prompt": "New prompt text"
  }
}

Field	Type	Meaning
job_id	string (required)	Target job’s UUID.
patch	object (required)	Any subset of: name, enabled, command, prompt, model, allowed_tools, session_target, delete_after_run, schedule, delivery.
approved	boolean	Approval for a changed shell command in supervised mode.

Caution

Passing "allowed_tools": [] in a patch clears the allowlist (all tools become available) — it does not mean “allow zero tools”. If you change command, the new command is re-validated against the security policy. Blocked in read-only mode and when rate-limited.

cron_run

Immediately force-executes a job outside its normal schedule, records the result in run history, and updates last-run metadata. It does not reschedule the job — next_run is unchanged. Useful for testing a job on demand.

{"job_id": "<uuid>", "approved": true}

Field	Type	Meaning
job_id	string (required)	Target job’s UUID.
approved	boolean	Approval for a medium-risk shell command in supervised mode.

Returns {job_id, status, duration_ms, output}. Shell jobs re-validate the command at run time (the policy may have changed since creation). Blocked in read-only mode and when rate-limited.

cron_runs

Returns recent execution history for a job: timestamps, status, duration, and truncated output. Read-only; no security restrictions.

{"job_id": "<uuid>", "limit": 10}

Field	Type	Meaning
job_id	string (required)	UUID string.
limit	integer	Number of runs to return; default 10.

Output is truncated to 500 characters per run in the tool response. The stored record holds up to 16 KB; how many records are retained per job is governed by cron.max_run_history.

schedule (legacy)

An earlier, shell-only scheduling tool. It supports a wider set of actions but only creates shell jobs, and its output goes only to logs — it has no delivery, no agent jobs, and no timezone control. Documented for backward compatibility; prefer cron_add for new integrations.

{"action": "create", "expression": "*/5 * * * *", "command": "backup.sh"}
{"action": "once", "delay": "30m", "command": "echo once"}
{"action": "list"}
{"action": "get", "id": "<uuid>"}
{"action": "pause", "id": "<uuid>"}
{"action": "resume", "id": "<uuid>"}
{"action": "cancel", "id": "<uuid>"}
{"action": "remove", "id": "<uuid>"}

Field	Type	Meaning
action	string (required)	create | add | once | list | get | cancel | remove | pause | resume.
expression	string	Cron expression (for create / add).
delay	string	Human delay such as "30m", "2h", "1d" (for once).
run_at	string	RFC 3339 timestamp for an absolute one-shot.
command	string	Shell command (required for create / add / once).
id	string	Job UUID for get / cancel / remove / pause / resume.
approved	boolean	Approval for supervised mode.

Tip

If you need the output delivered to Telegram, Discord, Slack, or another channel — or you want an agent prompt rather than a shell command — use cron_add. The two tools coexist and share the same job store, so jobs from either show up in cron_list.

Delivery / announce mode

The delivery object on cron_add and cron_update routes a job’s output to a chat channel after each run.

"delivery": {
  "mode": "announce",
  "channel": "discord",
  "to": "1234567890",
  "best_effort": true
}

Field	Type	Meaning
mode	string	"none" (default) or "announce".
channel	string	"telegram", "discord", "slack", "mattermost", "signal", "matrix", "qq", or "whatsapp".
to	string	Destination identifier (Discord channel ID, Telegram chat ID, Slack channel name, Matrix room ID, etc.).
best_effort	boolean	Default true. When false, a delivery failure marks the run as "error" even if the job itself succeeded.

Note

Before delivery, output is scanned for credential leaks and any detected secrets are redacted to [REDACTED]. The matrix and whatsapp channels are feature-gated at build time; using them in a binary built without the corresponding Cargo feature returns a clear error. See Channels overview for channel setup.

SOP tools

Standard Operating Procedures are deterministic, multi-step procedures defined as SOP.toml + SOP.md files on disk and run by Revka’s SOP engine. These tools let the agent list SOPs, start a run, walk it step by step, and clear approval gates. They require an SOPs directory to be configured (sop.sops_dir); see SOP reference: syntax, triggers & execution for definitions, triggers, and execution modes.

A typical loop is: sop_execute to start a run → repeat sop_advance (clearing any gate with sop_approve) until the run completes → sop_status to check state at any time.

Note

There is no revka sop run CLI command. Runs are initiated through sop_execute, or by an SOP’s configured triggers (manual, webhook, MQTT, cron, or peripheral). The CLI is for inspecting definitions: revka sop list, revka sop show, and revka sop validate.

sop_list

Lists all loaded SOPs with their triggers, priority, step count, and active-run count. Optional filters.

{"filter": "incident"}

Field	Type	Meaning
filter	string	Substring filter on the SOP name.
priority	string	Filter by priority level (low | normal | high | critical).

sop_execute

Manually triggers a SOP by name. Returns the run ID and the first step’s instruction. The run ID is required by every subsequent sop_advance, sop_approve, and sop_status call.

{"name": "incident-response"}

Field	Type	Meaning
name	string (required)	SOP name as shown by sop_list.

sop_advance

Reports the result of the current step and advances the run to the next step.

{"run_id": "run_abc123", "success": true, "output": "Backup completed successfully"}

Field	Type	Meaning
run_id	string (required)	Run ID from sop_execute.
success	boolean (required)	Whether the step succeeded.
output	string (required)	Brief output summary for this step.

sop_approve

Approves a step that is waiting for operator approval and returns the step instruction to execute. Approval gates appear in modes such as supervised and step_by_step, on steps marked requires_confirmation, and at deterministic checkpoints; a run paused on a gate shows status waiting_approval or paused_checkpoint.

{"run_id": "run_abc123"}

Field	Type	Meaning
run_id	string (required)	Run ID of the paused run.

sop_status

Queries SOP execution status. Pass a run_id for one run, a sop_name to list runs for a given SOP, or no arguments to show all active runs.

{}

{"run_id": "run_abc123"}

{"sop_name": "incident-response"}

Field	Type	Meaning
run_id	string	A specific run.
sop_name	string	List runs for this SOP.

Run status is one of pending, running, waiting_approval, paused_checkpoint, completed, failed, or cancelled.

Related pages

• Tools overview — how tools are registered and gated.
• revka cron — the CLI equivalent for creating and managing jobs.
• revka skills, workflows & sop — the revka sop CLI.
• Cron overview & expressions and Agent jobs & delivery — the cron model in depth.
• SOP reference: syntax, triggers & execution — SOP definitions and execution modes.
• Cron, sessions & attachments API — managing jobs over HTTP.