diff --git a/skills/agcron/managing-daemon/SKILL.md b/skills/agcron/managing-daemon/SKILL.md new file mode 100644 index 0000000..07237f4 --- /dev/null +++ b/skills/agcron/managing-daemon/SKILL.md @@ -0,0 +1,215 @@ +--- +name: managing-daemon +description: > + Start, stop, and check the status of the agent-cron daemon. + Use when you need to manage the daemon lifecycle, check if + the daemon is running, or troubleshoot daemon startup issues. +--- + +# Managing the Agent Cron Daemon + +This skill instructs you, the AI agent, on how to help a user start, stop, and +check the status of the agent-cron daemon. Follow each section as written. +Always show raw CLI output first, then provide your conversational interpretation. + +## Before You Start + +Run the following command to confirm the `agcron` binary is installed: + +```bash +which agcron +``` + +If the command prints a path (e.g., `/usr/local/bin/agcron`), the binary is +available. Proceed to the section the user needs. + +If the command prints nothing or returns "not found", tell the user: + +> The `agcron` binary is not on your PATH. You need to install it first. +> I can help you with that using the **installing-agcron** skill. + +Do not continue with any daemon operations until the binary is confirmed present. + +## Starting the Daemon + +**Requirements:** DAEM-01 (start), DAEM-04 (double-start prevention) + +### Step 1 — Check whether the daemon is already running + +Run: + +```bash +agcron status +``` + +Show the complete output to the user. + +**If the output contains "Status: running":** + +Tell the user the daemon is already running. Extract the PID and uptime from the +output and present them conversationally. For example: + +> The daemon is already running (PID 48201, uptime 3h 12m). No action needed. + +Do NOT attempt to start the daemon again. Ask if the user wants to do something +else instead (check status details, stop, etc.). + +**If the output contains "Error: Daemon is not running" (exit code 69):** + +Proceed to Step 2. + +### Step 2 — Start the daemon + +Run: + +```bash +agcron daemon -d +``` + +Show the complete output to the user. + +**Expected success output:** `Daemon started (backgrounded)` + +**If the output says "Daemon already running (PID N)":** This means a race +condition occurred between your status check and start attempt. Tell the user the +daemon is already running with that PID. Do not retry. + +### Step 3 — Verify the daemon started + +Run: + +```bash +agcron status +``` + +Show the complete output to the user. Confirm the daemon is running by checking +for "Status: running" in the output. Summarize the key fields: + +> The daemon started successfully. It is running as PID 48201 with N jobs loaded. +> The next scheduled run is at HH:MM. + +If the status still shows the daemon is not running, tell the user the start +failed and direct them to the Troubleshooting section. + +## Stopping the Daemon + +**Requirement:** DAEM-02 + +### Step 1 — Check whether the daemon is running + +Run: + +```bash +agcron status +``` + +Show the complete output to the user. + +If the output contains "Error: Daemon is not running", tell the user: + +> The daemon is not currently running, so there is nothing to stop. + +Do not attempt to stop it. Ask if they want to start it instead. + +### Step 2 — Stop the daemon + +If the daemon is running, run: + +```bash +agcron stop +``` + +Show the complete output to the user. + +**Expected output sequence:** + +1. `Stopping daemon...` — the daemon received the shutdown signal. +2. `Daemon stopped` — clean shutdown completed. + +**If the output contains "Warning: daemon may still be draining":** Tell the +user that in-flight jobs are still completing. The daemon will exit once all +running jobs finish or the shutdown timeout (default 30 seconds) is reached. +Suggest waiting a moment and then checking status: + +```bash +agcron status +``` + +### Step 3 — Confirm shutdown + +Run: + +```bash +agcron status +``` + +Show the complete output to the user. Confirm that the daemon is no longer +running: + +> The daemon has been stopped successfully. + +If it is still running, it may be draining in-flight jobs. Tell the user to wait +and check again, or refer to the Troubleshooting section. + +## Checking Status + +**Requirement:** DAEM-03 + +Run: + +```bash +agcron status +``` + +Show the complete raw output to the user first. Then interpret the fields. + +### When the daemon is running + +The output includes these fields: + +| Field | Meaning | +| ------------------ | ---------------------------------------------- | +| Status | `running` — daemon is active | +| PID | Process ID of the daemon | +| Uptime | How long the daemon has been running | +| Loaded Jobs | Number of cron job definitions currently loaded | +| Queue Depth | Number of jobs waiting to execute | +| Next Scheduled Run | When the next job will fire | +| Memory | Current memory usage of the daemon process | + +Provide a conversational summary. For example: + +> The daemon is healthy and running as PID 48201 (uptime 3h 12m). It has 5 jobs +> loaded with none queued. The next scheduled run is at 14:30 UTC. Memory usage +> is 12 MB. + +If queue depth is high relative to loaded jobs, note this: + +> Queue depth is 8 with only 3 jobs loaded. This may indicate jobs are backing +> up. Check concurrency settings or job execution times. + +### When the daemon is not running + +The output will contain "Error: Daemon is not running" and the exit code will be +69. Tell the user: + +> The daemon is not running. Would you like me to start it? + +## Troubleshooting + +If you encounter errors during any daemon operation, consult the troubleshooting +guide for diagnosis and resolution steps: + +See [references/troubleshooting.md](references/troubleshooting.md) + +Common issues include permission errors on the socket file, stale socket files +blocking startup, config parse errors, and daemons that hang during shutdown. +The troubleshooting guide provides the exact error messages and fix steps for +each case. + +## Reference Materials + +For the complete CLI command reference including all flags, environment +variables, and expected outputs, see: + +[references/cli-commands.md](references/cli-commands.md) diff --git a/skills/agcron/managing-daemon/references/cli-commands.md b/skills/agcron/managing-daemon/references/cli-commands.md new file mode 100644 index 0000000..d7ab4ee --- /dev/null +++ b/skills/agcron/managing-daemon/references/cli-commands.md @@ -0,0 +1,150 @@ +# Agent Cron Daemon CLI Command Reference + +## agcron daemon -d + +Start the daemon in background (detached) mode. + +**Usage:** + +```bash +agcron daemon -d +``` + +**Success output:** + +``` +Daemon started (backgrounded) +``` + +**Already running output:** + +``` +Daemon already running (PID 48201) +``` + +The daemon writes its PID to the configured PID file and opens a Unix domain +socket for CLI communication. + +## agcron daemon + +Start the daemon in foreground mode. This is primarily useful during development +or debugging, as log output goes directly to the terminal. + +**Usage:** + +```bash +agcron daemon +``` + +The daemon runs in the foreground until interrupted. Press `Ctrl+C` to trigger a +graceful shutdown (equivalent to `agcron stop`). + +## agcron status + +Show the current daemon status. + +**Usage:** + +```bash +agcron status +``` + +**When running — output fields:** + +``` +Status: running +PID: 48201 +Uptime: 3h 12m +Loaded Jobs: 5 +Queue Depth: 0 +Next Scheduled Run: 2026-03-10 14:30:00 UTC +Memory: 12 MB +``` + +| Field | Description | +| ------------------ | --------------------------------------------------- | +| Status | `running` when the daemon is active | +| PID | Operating system process ID | +| Uptime | Duration since the daemon started | +| Loaded Jobs | Count of parsed cron job definitions from `.cron/jobs/` | +| Queue Depth | Number of jobs currently waiting to execute | +| Next Scheduled Run | Timestamp of the next job scheduled to fire | +| Memory | Resident memory usage of the daemon process | + +**When not running:** + +``` +Error: Daemon is not running +``` + +Exit code: `69` (EX_UNAVAILABLE). + +## agcron stop + +Gracefully shut down a running daemon. + +**Usage:** + +```bash +agcron stop +``` + +**Output sequence:** + +``` +Stopping daemon... +Daemon stopped +``` + +The stop command sends a shutdown signal via the Unix domain socket. The daemon +will finish any in-flight jobs before exiting, up to the configured +`shutdown_timeout_secs` (default: 30 seconds). + +**If jobs are still draining:** + +``` +Stopping daemon... +Warning: daemon may still be draining +``` + +This means in-flight jobs have not yet completed. The daemon will exit once they +finish or the shutdown timeout is reached. + +**If the daemon is not running:** + +``` +Error: Daemon is not running +``` + +## agcron --version + +Display the installed version of the agcron binary. + +**Usage:** + +```bash +agcron --version +``` + +**Output:** + +``` +agcron 1.6.0 +``` + +## Environment Variables + +| Variable | Description | Default | +| -------------------- | ---------------------------------------------- | ------------------------------------ | +| AGENT_CRON_CONFIG | Path to the configuration file | `~/.config/agent-cron/config.toml` | +| AGENT_CRON_SOCKET | Path to the Unix domain socket | `~/.config/agent-cron/agent-cron.sock` | +| CRON_MAX_CONCURRENCY | Maximum concurrent job executions | `4` | +| RUST_LOG | Log level filter (e.g., `debug`, `info,agcron=trace`) | `info` | + +## Configuration File + +**Location:** `~/.config/agent-cron/config.toml` + +The daemon reads this file on startup. It defines managed project directories, +concurrency limits, default adapters, and transport preferences. Changes to the +config file require a daemon restart to take effect. diff --git a/skills/agcron/managing-daemon/references/troubleshooting.md b/skills/agcron/managing-daemon/references/troubleshooting.md new file mode 100644 index 0000000..6853d9b --- /dev/null +++ b/skills/agcron/managing-daemon/references/troubleshooting.md @@ -0,0 +1,154 @@ +# Daemon Troubleshooting Guide + +## "Daemon already running (PID N)" + +**When you see this:** Running `agcron daemon -d` when the daemon is already +started. + +**Cause:** A daemon process is already active with the given PID. + +**Fix:** + +1. Run `agcron status` to confirm the daemon is running and healthy. +2. If you need to restart it, run `agcron stop` first, then `agcron daemon -d`. +3. If the PID shown does not correspond to a live process (stale PID file), see + the "Address already in use" section below. + +## "Error: Daemon is not running" + +**When you see this:** Running `agcron status` or `agcron stop` when no daemon +process is active. + +**Cause:** The daemon has not been started, or it exited unexpectedly. + +**Fix:** + +1. Start the daemon: `agcron daemon -d` +2. If it was previously running and crashed, check logs for the cause. Run in + foreground mode for diagnostic output: `RUST_LOG=debug agcron daemon` + +## "Permission denied on socket" + +**When you see this:** Running any `agcron` command that communicates with the +daemon. + +**Cause:** The Unix domain socket file exists but was created by a different user +or with restrictive permissions. This commonly happens when the daemon was +previously run as root or a different user account. + +**Fix:** + +1. Check the socket file permissions: + ```bash + ls -la ~/.config/agent-cron/agent-cron.sock + ``` +2. Remove the stale socket file: + ```bash + rm ~/.config/agent-cron/agent-cron.sock + ``` +3. Verify the directory has correct ownership: + ```bash + ls -la ~/.config/agent-cron/ + ``` +4. If the directory is owned by another user, fix ownership: + ```bash + sudo chown -R $(whoami) ~/.config/agent-cron/ + ``` +5. Start the daemon again: `agcron daemon -d` + +## "Address already in use" + +**When you see this:** Starting the daemon with `agcron daemon -d` or +`agcron daemon`. + +**Cause:** A stale Unix domain socket file remains from a previous daemon run +that did not clean up properly (e.g., killed with SIGKILL, system crash). + +**Fix:** + +1. Confirm the daemon is not actually running: + ```bash + agcron status + ``` +2. If status reports "Error: Daemon is not running", remove the stale socket: + ```bash + rm ~/.config/agent-cron/agent-cron.sock + ``` +3. If a custom socket path is configured, remove that instead: + ```bash + rm $AGENT_CRON_SOCKET + ``` +4. Start the daemon: `agcron daemon -d` + +## "Config parse error" + +**When you see this:** Starting the daemon. The error message will include a +line number or key name from the TOML file. + +**Cause:** The configuration file at `~/.config/agent-cron/config.toml` contains +invalid TOML syntax or unrecognized keys. + +**Fix:** + +1. Run the daemon with debug logging to see the full error: + ```bash + RUST_LOG=debug agcron daemon + ``` +2. Check the config file syntax: + ```bash + cat ~/.config/agent-cron/config.toml + ``` +3. Common syntax issues: + - Missing quotes around string values + - Unclosed brackets in array values + - Duplicate key names + - Using `=` instead of `:` (TOML uses `=`) +4. Fix the syntax error and retry: `agcron daemon -d` + +## "Binary not found" / "command not found: agcron" + +**When you see this:** Running any `agcron` command. + +**Cause:** The `agcron` binary is not installed or not on your shell's PATH. + +**Fix:** + +1. Check if the binary exists somewhere: + ```bash + find /usr/local/bin /usr/bin ~/.cargo/bin -name agcron 2>/dev/null + ``` +2. If found, add its directory to your PATH: + ```bash + export PATH="$PATH:/path/to/directory" + ``` + Add this line to your shell profile (`~/.bashrc`, `~/.zshrc`) for persistence. +3. If not found, install agent-cron. Use the **installing-agcron** skill for + guided installation. + +## Daemon won't stop / hangs on shutdown + +**When you see this:** Running `agcron stop` produces "Stopping daemon..." but +never shows "Daemon stopped", or shows "Warning: daemon may still be draining". + +**Cause:** In-flight jobs are still executing. The daemon waits for them to +complete before exiting, up to `shutdown_timeout_secs` (default: 30 seconds). + +**Fix:** + +1. Wait for the shutdown timeout to elapse (up to 30 seconds by default). +2. Check if jobs are still running: + ```bash + agcron status + ``` +3. If the daemon is still draining after the timeout period, it may be stuck. + As a last resort, find and kill the process: + ```bash + agcron status # note the PID + kill + ``` +4. If `kill` does not work, use `kill -9 ` — but note this will + terminate in-flight jobs immediately without cleanup. +5. After a forced kill, clean up the stale socket: + ```bash + rm ~/.config/agent-cron/agent-cron.sock + ```