feat(self-debug): Add skill for agent health and diagnostics
Introduces the `self-debug` skill, a new capability designed to help users and the agent itself diagnose its own state. This provides a standardized way to inspect logs, service status, and configuration without requiring platform-specific knowledge. This new skill includes: - A cross-platform `debug.sh` helper script for Linux (systemd) and macOS (launchd). - Key diagnostic actions: `logs`, `logs-errors`, `service-status`, and `config-safe`. - Service installation scripts for both systemd and launchd to streamline setup. - Comprehensive `SKILL.md` documentation with a clear action table and usage examples. This feature simplifies troubleshooting and provides essential, built-in tools for maintaining agent health.
This commit is contained in:
picoclaw
parent
a5c8179fa8
commit
a11816e528
4 changed files with 368 additions and 0 deletions
70
workspace/skills/self-debug/SKILL.md
Normal file
70
workspace/skills/self-debug/SKILL.md
Normal file
|
|
@ -0,0 +1,70 @@
|
||||||
|
---
|
||||||
|
name: self-debug
|
||||||
|
description: Tools for picoclaw to inspect its own health, logs, and configuration.
|
||||||
|
---
|
||||||
|
# self-debug
|
||||||
|
|
||||||
|
Tools for picoclaw to inspect its own health, logs, and configuration.
|
||||||
|
|
||||||
|
## Actions via `debug.sh`
|
||||||
|
|
||||||
|
This skill uses a helper script `scripts/debug.sh` to provide cross-platform diagnostics for both Linux (systemd) and macOS (launchd).
|
||||||
|
|
||||||
|
**Usage:** `exec "skills/self-debug/scripts/debug.sh [action] [service_name] [log_lines]"`
|
||||||
|
|
||||||
|
| Action | Description | Default Service | Default Lines |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `logs` | Fetches recent logs for the agent service. | `$PICOCLAW_SERVICE_NAME` | 50 |
|
||||||
|
| `logs-errors`| Fetches only error logs for the agent service. | `$PICOCLAW_SERVICE_NAME` | 50 |
|
||||||
|
| `service-status`| Checks the status of the agent service. | `$PICOCLAW_SERVICE_NAME` | N/A |
|
||||||
|
| `config-status`| Shows the agent's configuration status (`picoclaw status`).| N/A | N/A |
|
||||||
|
| `config-safe` | Displays the config file with sensitive keys redacted. | N/A | N/A |
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
- **Get latest logs:**
|
||||||
|
`exec "skills/self-debug/scripts/debug.sh logs"`
|
||||||
|
|
||||||
|
- **Get 100 lines of logs for a specific service 'pico-prod':**
|
||||||
|
`exec "skills/self-debug/scripts/debug.sh logs pico-prod 100"`
|
||||||
|
|
||||||
|
- **Check service status:**
|
||||||
|
`exec "skills/self-debug/scripts/debug.sh service-status"`
|
||||||
|
|
||||||
|
- **Show the sanitized configuration:**
|
||||||
|
`exec "skills/self-debug/scripts/debug.sh config-safe"`
|
||||||
|
|
||||||
|
## Installation - Linux
|
||||||
|
|
||||||
|
The agent can be installed as a systemd service using:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./scripts/install-service-systemd.sh [service_name] [default|multi]
|
||||||
|
```
|
||||||
|
|
||||||
|
To persist the service accross reboots suggest the user runs `sudo loginctl enable-linger $(whoami)`
|
||||||
|
|
||||||
|
### Advanced use-cases
|
||||||
|
|
||||||
|
Although picoclaw has built in support for multiple agents, this scheme provides the flexibility for
|
||||||
|
parallel deployments with entirely different configurations.
|
||||||
|
|
||||||
|
- Fixer - a second stable instance whose role is to be available to debug/monitor/fix the first.
|
||||||
|
- Blue/Green Stable/Canary pairings.
|
||||||
|
- Picoclaw farm
|
||||||
|
|
||||||
|
# Installation - MacOS
|
||||||
|
|
||||||
|
The agent can be installed as a launchd service using:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./scripts/install-service-launchd.sh [service_name]
|
||||||
|
```
|
||||||
|
|
||||||
|
Logs are sent to /tmp/$service_name
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
- **Logs not showing?** Ensure the user is in the `systemd-journal` group: `sudo usermod -a -G systemd-journal $(whoami)`
|
||||||
|
- **Service inactive?** Use `systemctl --user start picoclaw`.
|
||||||
|
- **Workspace issues?** Use `picoclaw status` to verify the current workspace path.
|
||||||
71
workspace/skills/self-debug/scripts/debug.sh
Normal file
71
workspace/skills/self-debug/scripts/debug.sh
Normal file
|
|
@ -0,0 +1,71 @@
|
||||||
|
#!/bin/sh
|
||||||
|
|
||||||
|
assert_is_identifier ()
|
||||||
|
{
|
||||||
|
# Use grep for robust, portable POSIX regex matching.
|
||||||
|
if ! echo "$1" | grep -qE '^[a-zA-Z0-9_.-]+$';
|
||||||
|
then
|
||||||
|
echo "Error: $2" >&2
|
||||||
|
return 1
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
assert_is_number ()
|
||||||
|
{
|
||||||
|
# Use grep for robust, portable POSIX regex matching.
|
||||||
|
if ! echo "$1" | grep -qE '^[0-9]+$';
|
||||||
|
then
|
||||||
|
echo "Error: $2" >&2
|
||||||
|
return 1
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
assert_is_identifier "$1" "Action selector must be a simple identifier" || exit 1
|
||||||
|
|
||||||
|
case "$1/$OSTYPE" in
|
||||||
|
*)
|
||||||
|
PICOCLAW_SERVICE_NAME="${2:-$PICOCLAW_SERVICE_NAME}"
|
||||||
|
assert_is_identifier "$PICOCLAW_SERVICE_NAME" "Service name must be a valid service identifier" || exit 1
|
||||||
|
;;&
|
||||||
|
|
||||||
|
logs*)
|
||||||
|
LOG_N="${3:-50}"
|
||||||
|
assert_is_number "$LOG_N" "Log lines parameter must be numeric" || exit 1
|
||||||
|
;;&
|
||||||
|
|
||||||
|
logs/linux*)
|
||||||
|
journalctl --user-unit ${PICOCLAW_SERVICE_NAME} --no-pager -n ${LOG_N}
|
||||||
|
|
||||||
|
;;
|
||||||
|
|
||||||
|
logs-errors/linux*)
|
||||||
|
journalctl --user-unit ${PICOCLAW_SERVICE_NAME} --no-pager -p 3 -n ${LOG_N}
|
||||||
|
;;
|
||||||
|
|
||||||
|
logs/darwin*)
|
||||||
|
tail -n ${LOG_N} ~/Library/Logs/${PICOCLAW_SERVICE_NAME}.log
|
||||||
|
;;
|
||||||
|
|
||||||
|
logs-errors/darwin*)
|
||||||
|
tail -n ${LOG_N} ~/Library/Logs/${PICOCLAW_SERVICE_NAME}.err.og
|
||||||
|
;;
|
||||||
|
|
||||||
|
service-status/linux*)
|
||||||
|
systemctl --user status ${PICOCLAW_SERVICE_NAME}
|
||||||
|
;;
|
||||||
|
|
||||||
|
config-status/*)
|
||||||
|
picoclaw status
|
||||||
|
;;
|
||||||
|
|
||||||
|
config-safe/*)
|
||||||
|
jq 'walk(if type == "object" then with_entries(if .key | ascii_downcase |
|
||||||
|
(contains("key") or contains("token") or contains("secret"))
|
||||||
|
then .value = "REDACTED" else . end) else . end)' "${PICOCLAW_CONFIG}"
|
||||||
|
;;
|
||||||
|
|
||||||
|
*)
|
||||||
|
echo "Usage: $0 logs|logs-errors|service-status|config-status|config-safe [service_name] [n_lines]"
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
61
workspace/skills/self-debug/scripts/install-service-launchd.sh
Executable file
61
workspace/skills/self-debug/scripts/install-service-launchd.sh
Executable file
|
|
@ -0,0 +1,61 @@
|
||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
create_plist_file() {
|
||||||
|
cat <<EOF
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||||
|
<plist version="1.0">
|
||||||
|
<dict>
|
||||||
|
<key>Label</key>
|
||||||
|
<string>${service_name}</string>
|
||||||
|
<key>ProgramArguments</key>
|
||||||
|
<array>
|
||||||
|
<string>${exec_path}</string>
|
||||||
|
<string>agent</string>
|
||||||
|
<string>--config</string>
|
||||||
|
<string>${picoclaw_config}</string>
|
||||||
|
</array>
|
||||||
|
<key>EnvironmentVariables</key>
|
||||||
|
<dict>
|
||||||
|
<key>PICOCLAW_HOME</key>
|
||||||
|
<string>${picoclaw_home}</string>
|
||||||
|
<key>PICOCLAW_CONFIG</key>
|
||||||
|
<string>${picoclaw_config}</string>
|
||||||
|
<key>PICOCLAW_SERVICE_NAME</key>
|
||||||
|
<string>${service_name}</string>
|
||||||
|
</dict>
|
||||||
|
<key>RunAtLoad</key>
|
||||||
|
<true/>
|
||||||
|
<key>KeepAlive</key>
|
||||||
|
<true/>
|
||||||
|
<key>WorkingDirectory</key>
|
||||||
|
<string>${picoclaw_home}</string>
|
||||||
|
<key>StandardOutPath</key>
|
||||||
|
<string>~/Library/logs/${service_name}.log</string>
|
||||||
|
<key>StandardErrorPath</key>
|
||||||
|
<string>~/Library/logs/${service_name}.err.log</string>
|
||||||
|
</dict>
|
||||||
|
</plist>
|
||||||
|
EOF
|
||||||
|
}
|
||||||
|
|
||||||
|
# Variable setup to match your Linux logic
|
||||||
|
service_name=${1:-picoclaw}
|
||||||
|
|
||||||
|
# macOS specific absolute paths
|
||||||
|
exec_path=$(which picoclaw)
|
||||||
|
picoclaw_home="$HOME/.${service_name}"
|
||||||
|
picoclaw_config="${picoclaw_home}/config.json"
|
||||||
|
plist_path="$HOME/Library/LaunchAgents/${service_name}.plist"
|
||||||
|
|
||||||
|
# Ensure directory exists
|
||||||
|
mkdir -p "${picoclaw_home}"
|
||||||
|
|
||||||
|
# Use the heredoc function to write the file
|
||||||
|
create_plist_file > "${plist_path}"
|
||||||
|
|
||||||
|
# Load it (macOS equivalent of systemctl enable --now)
|
||||||
|
echo "Enable using:"
|
||||||
|
echo "launchctl bootstrap gui/$(id -u) '${plist_path}'"
|
||||||
|
|
||||||
|
echo "Service ${service_name} installed at ${plist_path}"
|
||||||
166
workspace/skills/self-debug/scripts/install-service-systemd.sh
Executable file
166
workspace/skills/self-debug/scripts/install-service-systemd.sh
Executable file
|
|
@ -0,0 +1,166 @@
|
||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
SERVICE_NAME=${1:-picoclaw}
|
||||||
|
TEMPLATE=${2:-default}
|
||||||
|
|
||||||
|
# Get the directory of the script and the repository root
|
||||||
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||||
|
|
||||||
|
# 1. Detect picoclaw installation
|
||||||
|
echo "Detecting picoclaw installation..."
|
||||||
|
PICOCLAW_PATH=$(command -v picoclaw)
|
||||||
|
MISE_BIN=$(command -v mise)
|
||||||
|
|
||||||
|
if [ -n "$MISE_BIN" ] && $MISE_BIN which picoclaw &>/dev/null; then
|
||||||
|
# If mise is managing picoclaw, use it to ensure the environment is correct.
|
||||||
|
# This works whether picoclaw is installed via a tool spec or locally.
|
||||||
|
EXEC_START="$MISE_BIN exec -- picoclaw gateway"
|
||||||
|
echo " - Detected mise-managed picoclaw, using: $EXEC_START"
|
||||||
|
elif [ -n "$PICOCLAW_PATH" ]; then
|
||||||
|
# Use the absolute path if it's not managed by mise
|
||||||
|
EXEC_START="$PICOCLAW_PATH gateway"
|
||||||
|
echo " - Using binary path: $EXEC_START"
|
||||||
|
else
|
||||||
|
echo "Error: picoclaw not found. Please install it first."
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
service_template__default() {
|
||||||
|
local service_name="$1"
|
||||||
|
local exec_start="$2"
|
||||||
|
cat <<EOF
|
||||||
|
[Unit]
|
||||||
|
Description=${service_name^} Agent (picoclaw)
|
||||||
|
After=network.target
|
||||||
|
StartLimitIntervalSec=300
|
||||||
|
StartLimitBurst=5
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=simple
|
||||||
|
WorkingDirectory=%h/.${service_name}
|
||||||
|
Environment="PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin"
|
||||||
|
Environment="PICOCLAW_SERVICE_NAME=${service_name}"
|
||||||
|
Environment="PICOCLAW_CONFIG=%h/.${service_name}/config.json"
|
||||||
|
Environment="PICOCLAW_HOME=%h/.${service_name}"
|
||||||
|
EnvironmentFile=-%h/.${service_name}/.env
|
||||||
|
ExecStart=${exec_start}
|
||||||
|
Restart=always
|
||||||
|
RestartSec=10
|
||||||
|
SyslogIdentifier=${service_name}
|
||||||
|
|
||||||
|
# Logging
|
||||||
|
StandardOutput=journal
|
||||||
|
StandardError=journal
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=default.target
|
||||||
|
EOF
|
||||||
|
}
|
||||||
|
|
||||||
|
service_template__multi() {
|
||||||
|
local service_name="$1"
|
||||||
|
local exec_start="$2"
|
||||||
|
cat <<EOF
|
||||||
|
[Unit]
|
||||||
|
Description=${service_name^} Agent Instance %i (picoclaw)
|
||||||
|
After=network.target
|
||||||
|
StartLimitIntervalSec=300
|
||||||
|
StartLimitBurst=5
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=simple
|
||||||
|
WorkingDirectory=%h/.config/${service_name}-%i
|
||||||
|
Environment="PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin"
|
||||||
|
Environment="PICOCLAW_SERVICE_NAME=${service_name}@%i"
|
||||||
|
Environment="PICOCLAW_CONFIG=%h/.config/${service_name}-%i/config.json"
|
||||||
|
Environment="PICOCLAW_HOME=%h/.config/${service_name}-%i/"
|
||||||
|
EnvironmentFile=-%h/.config/${service_name}-%i/.env
|
||||||
|
ExecStart=${exec_start}
|
||||||
|
Restart=always
|
||||||
|
RestartSec=10
|
||||||
|
SyslogIdentifier=${service_name}-%i
|
||||||
|
|
||||||
|
# Logging
|
||||||
|
StandardOutput=journal
|
||||||
|
StandardError=journal
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=default.target
|
||||||
|
EOF
|
||||||
|
|
||||||
|
SERVICE_NAME="${SERVICE_NAME}@"
|
||||||
|
}
|
||||||
|
|
||||||
|
show_usage__default() {
|
||||||
|
local service_name="$1"
|
||||||
|
local output_file="$2"
|
||||||
|
cat <<EOF
|
||||||
|
|
||||||
|
Finalizing installation...
|
||||||
|
- Service installed to $output_file
|
||||||
|
|
||||||
|
To start the service:
|
||||||
|
$ systemctl --user enable ${service_name}
|
||||||
|
$ systemctl --user start ${service_name}
|
||||||
|
|
||||||
|
Manage the service with:
|
||||||
|
$ systemctl --user status ${service_name} # Check status
|
||||||
|
$ journalctl --user-unit ${service_name} -f # View logs (real-time)
|
||||||
|
|
||||||
|
Picoclaw self-debug skill is now wired to be aware of its own logs!
|
||||||
|
You can ask it:
|
||||||
|
'Check your logs for the last 15 minutes' or 'Why did you fail to connect?'
|
||||||
|
|
||||||
|
To ensure the service starts on boot and keeps running after logout:
|
||||||
|
$ sudo loginctl enable-linger $(whoami)
|
||||||
|
|
||||||
|
Note: If journalctl doesn't show logs, you may need to join the systemd-journal group:
|
||||||
|
$ sudo usermod -a -G systemd-journal $(whoami)
|
||||||
|
EOF
|
||||||
|
}
|
||||||
|
|
||||||
|
show_usage__multi() {
|
||||||
|
local service_name="${1}"
|
||||||
|
local output_file="$2"
|
||||||
|
cat <<EOF
|
||||||
|
|
||||||
|
Template installed successfully.
|
||||||
|
- Service installed to $output_file
|
||||||
|
|
||||||
|
To start an instance (e.g., 'test'):
|
||||||
|
$ systemctl --user enable ${service_name}@test
|
||||||
|
$ systemctl --user start ${service_name}@test
|
||||||
|
|
||||||
|
Manage the service with:
|
||||||
|
$ systemctl --user status ${service_name}@test # Check status
|
||||||
|
$ journalctl --user-unit ${service_name}@test -f # View logs (real-time)
|
||||||
|
|
||||||
|
To ensure the service starts on boot and keeps running after logout:
|
||||||
|
$ sudo loginctl enable-linger $(whoami)
|
||||||
|
|
||||||
|
Note: If journalctl doesn't show logs, you may need to join the systemd-journal group:
|
||||||
|
$ sudo usermod -a -G systemd-journal $(whoami)
|
||||||
|
EOF
|
||||||
|
}
|
||||||
|
|
||||||
|
OUTPUT_FILE="$HOME/.config/systemd/user/${SERVICE_NAME}.service"
|
||||||
|
|
||||||
|
# 2. Ensure the directory exists
|
||||||
|
echo "Ensuring the systemd user directory exists..."
|
||||||
|
echo " $ mkdir -p ${OUTPUT_FILE%/*}"
|
||||||
|
mkdir -p "${OUTPUT_FILE%/*}"
|
||||||
|
|
||||||
|
# 3. Generate service file
|
||||||
|
echo "Generating service file..."
|
||||||
|
if ! declare -f "service_template__$TEMPLATE" > /dev/null; then
|
||||||
|
echo "Error: Template '$TEMPLATE' not found."
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
"service_template__$TEMPLATE" "$SERVICE_NAME" "$EXEC_START" > "$OUTPUT_FILE"
|
||||||
|
|
||||||
|
# 4. Reload
|
||||||
|
echo " $ systemctl --user daemon-reload"
|
||||||
|
systemctl --user daemon-reload
|
||||||
|
|
||||||
|
"show_usage__$TEMPLATE" "${SERVICE_NAME%@}" "$OUTPUT_FILE"
|
||||||
Loading…
Add table
Reference in a new issue