SysClaw Reporting

Report system issues and submit resource requests to SysClaw via the cross-agent communication system. Use when an agent needs to report an error, warning, o...

SysClaw Reporting (Client)

Report issues and submit requests to SysClaw. This is the client-side skill — it covers how to communicate with SysClaw, not how SysClaw processes requests.

Prerequisites

1. Install Python dependency

pip3 install psycopg2-binary

2. Set environment variables

Set these before running scripts. All scripts use a fallback chain: script-specific vars → SYSCLAW_DB_* → defaults.

# Shared connection settings (used by all scripts as fallback)
export SYSCLAW_DB_HOST="<your-db-host>"        # Ask your SysClaw operator
export SYSCLAW_DB_PORT="5432"
export SYSCLAW_DB_NAME="system_comm"
export SYSCLAW_DB_USER="<your-agent-role>"     # e.g., jobagent, pmagent, researcher_agent
export SYSCLAW_DB_PASSWORD="<your-db-password>"

You can also set per-script overrides (ISSUE_DB_*, REQUEST_DB_*) if different scripts need different credentials, but in most cases the shared SYSCLAW_DB_* vars are sufficient.

Ask your SysClaw operator for the correct host address and your agent credentials.

Report an Issue

For errors, warnings, and problems that need attention:

scripts/report-issue.sh <source> <severity> <title> [category] [details] [source_host]

Severity: info | warning | critical Categories: disk | service | error | resource | network | config | other

Examples:

scripts/report-issue.sh jobhunter warning "Disk usage above 80%" disk "df shows 82% on /data" srv-prod-01
scripts/report-issue.sh pmagent critical "API endpoint returning 500" service "5 consecutive failures" srv-prod-02

source_host (6th argument, optional): Identifies which machine this report originates from. Defaults to the current hostname if omitted.

Request Something from SysClaw

For software installs, access requests, configuration changes, and more:

scripts/request-resource.sh <source> <type> <action> <target> <justification> [urgency] [payload] [source_host]

Types: access | software | resource | config | service | deployment | info Actions: install | remove | create | modify | restart | grant | check | deploy Urgency: low | normal | urgent (default: normal) Payload: Valid JSON string (optional). Validated before submission.

Examples

scripts/request-resource.sh jobhunter software install nginx '{"version":"latest"}' normal
scripts/request-resource.sh pmagent access grant /var/data/pm '{"level":"read"}'
scripts/request-resource.sh researcher info check disk_usage

What Happens Next

1. Your request is submitted and SysClaw is automatically notified
2. SysClaw assesses and processes the request (typically within 15 minutes)
3. SysClaw executes approved actions — you don't need to do anything after approval
4. You receive a notification with the result (e.g., "DONE: nginx installed and running")

Verdicts:

• approved + DONE — SysClaw completed the work, see notification for details
• denied — see notification for reason
• escalated — human operator reviewing, you'll be notified when decided

Check Notifications

Check for responses from SysClaw:

scripts/check-notifications.sh <your-agent-name>        # View unread
scripts/check-notifications.sh <your-agent-name> yes    # View and mark as read

Workflow:

1. Run check-notifications.sh at session start or after submitting a request
2. Read the results — SysClaw has already done the work for approved requests
3. Mark as read when done

Automatic Notification Checking

Set up a cron job so responses are ready when your session starts:

# Create wrapper script
cat > /usr/local/bin/check-sysclaw-notifications.sh << 'SCRIPT'
#!/bin/bash
export SYSCLAW_DB_HOST="<db-host>"
export SYSCLAW_DB_PORT="5432"
export SYSCLAW_DB_NAME="system_comm"
export SYSCLAW_DB_USER="<your-role>"
export SYSCLAW_DB_PASSWORD="<your-password>"
bash "<skill-path>/scripts/check-notifications.sh" <your-agent-name> > "<workspace>/memory/notifications.md" 2>/dev/null
SCRIPT
chmod +x /usr/local/bin/check-sysclaw-notifications.sh

# Add to crontab
(crontab -l 2>/dev/null; echo "*/15 * * * * /usr/local/bin/check-sysclaw-notifications.sh") | crontab -

Then at session start: cat memory/notifications.md

Direct SQL (Alternative to Scripts)

If you prefer direct database access:

-- Report issue
INSERT INTO issues (source, severity, category, title, details, source_host)
VALUES ('jobhunter', 'warning', 'disk', 'Disk usage high', 'Partition at 85%', 'srv-prod-01');

-- Submit request
INSERT INTO agent_requests (requesting_agent, request_type, action, target, justification, urgency, payload, source_host)
VALUES ('pmagent', 'software', 'install', 'nginx', 'Need web server', 'normal', '{"version":"latest"}'::jsonb, 'srv-prod-02');

-- Notify SysClaw (after submitting request)
INSERT INTO notifications (recipient, sender, related_request, message, urgency)
VALUES ('sysclaw', 'pmagent', <request_id>, 'New software request: install nginx', 'normal');

-- Check responses
SELECT * FROM notifications WHERE recipient = 'pmagent' AND read = FALSE;

Do not set verdict, security_assessment, resolved_at, or resolved_by — SysClaw manages these.

Post-Install

1. TOOLS.md — Add DB host, user, and connection details
2. Set up notification cron job — See "Automatic Notification Checking" above
3. Test:

   scripts/report-issue.sh <your-source> info "SysClaw reporting skill installed - test"
   

Technical Notes

• Scripts use Python psycopg2 with parameterized queries (no SQL injection risk)
• JSON payloads are validated with json.loads() before database insertion
• Connection retry: 3 attempts with exponential backoff (1s, 2s, 4s) on initial connection failure
• Mid-session reconnect: If the connection drops between queries, scripts reconnect and retry once automatically
• Connection timeout is 10 seconds per attempt (override with PGCONNECT_TIMEOUT)
• All scripts exit non-zero on failure with descriptive error messages