clawlog-status-sync - SKILL.md Agent Skill

name: clawlog-status-sync description: Synchronize long-running agent tasks to a ClawLog FastAPI backend with step updates, heartbeat signals, and soft-stop control polling. Use when the user asks to visualize agent progress, publish step-by-step execution summaries, monitor task liveness, or interrupt running work via soft_stop.

ClawLog Status Sync

Overview

Use this skill to keep agent execution state outside chat context by writing task events to ClawLog. Use write-only updates (heartbeat and step status), then read only control state (interrupt_requested) before each major block.

Workflow

1) Initialize Task

Create a task and step list in ClawLog before execution.

python scripts/create_task.py \
  --base-url http://localhost:8000 \
  --title "部署 Nginx 服务" \
  --step "检查本地环境" \
  --step "编写配置文件" \
  --step "启动并测试"

Persist task_id and step_id mapping in local runtime state (not in long chat text).

2) Execute With Status Updates

Before each major logic block, check soft-stop signal.

python scripts/update_status.py --task-id "$TASK_ID" --check-interrupt
# exit code 20 => stop requested

Mark step state transitions:

python scripts/update_status.py \
  --task-id "$TASK_ID" \
  --step-id "$STEP_ID" \
  --step-status running \
  --step-summary "starting config generation"

python scripts/update_status.py \
  --task-id "$TASK_ID" \
  --step-id "$STEP_ID" \
  --step-status done \
  --step-summary "nginx.conf generated and validated"

Send heartbeat every 10-20 seconds during long blocks:

python scripts/update_status.py \
  --task-id "$TASK_ID" \
  --heartbeat \
  --heartbeat-summary "writing config template"

3) Honor Soft Stop At Safe Boundary

If control check returns exit code 20, complete current safe boundary, then acknowledge interrupt.

python scripts/update_status.py \
  --task-id "$TASK_ID" \
  --ack-interrupt \
  --ack-summary "stopped after current step"

4) Keep Updates Compact

Write short summaries (recommended <= 120 chars). Do not include full logs or stack traces in summaries. Store rich logs in external files; publish only concise progress notes to ClawLog.

Failure Handling

Retry transient API failures up to 3 attempts with short backoff. If status sync remains unavailable, surface a clear warning and continue only if user explicitly prioritizes task execution over observability.

Resources

API contract and event meanings: references/api-contract.md
Task creation helper: scripts/create_task.py
Status and control helper: scripts/update_status.py
Polling helper for external watchers: scripts/poll_interrupt.py