From 5f841e6e4a72db952fd3a1d5916ce4025ad6998f Mon Sep 17 00:00:00 2001 From: shokollm <270575765+shokollm@users.noreply.github.com> Date: Thu, 2 Apr 2026 04:06:39 +0000 Subject: [PATCH] chore: documentation updates and quick fixes - Add missing command docs to SKILL.md (delegate, logs, status, doctor, notify, server, queue) - Add KUGETSU_VERBOSITY to config options table - Delete outdated test-kugetsu.sh (tests non-existent resume/stop commands) - Fix Phase 3 status in kugetsu-architecture.md (was In Progress, now Implemented) - Fix env rm quote handling (use grep -v instead of sed) - Add error handling for opencode init command --- docs/kugetsu-architecture.md | 2 +- skills/kugetsu/SKILL.md | 85 ++++++++ skills/kugetsu/scripts/kugetsu | 8 +- skills/kugetsu/tests/test-kugetsu.sh | 277 --------------------------- 4 files changed, 92 insertions(+), 280 deletions(-) delete mode 100755 skills/kugetsu/tests/test-kugetsu.sh diff --git a/docs/kugetsu-architecture.md b/docs/kugetsu-architecture.md index 027d5d5..da1e09c 100644 --- a/docs/kugetsu-architecture.md +++ b/docs/kugetsu-architecture.md @@ -326,7 +326,7 @@ When a Coding Agent starts, it: | Phase 1 | ✅ Complete | SSH + Tailscale remote access | | Phase 1b | ✅ Complete | Tailscale VPN setup | | Phase 2 | 📋 Planned | API Interface | -| Phase 3 | 🔄 In Progress | Chat Integration (Telegram) | +| Phase 3 | ✅ Implemented | Chat Integration (Telegram) | | Phase 4 | 📋 Planned | Web Dashboard | ### 6.2 Current Implementation diff --git a/skills/kugetsu/SKILL.md b/skills/kugetsu/SKILL.md index c3a7684..5f3fa74 100644 --- a/skills/kugetsu/SKILL.md +++ b/skills/kugetsu/SKILL.md @@ -48,6 +48,7 @@ A default config file is created during `kugetsu init` with commented examples: |----------|---------|-------------| | `MAX_CONCURRENT_AGENTS` | 3 | Maximum number of concurrent dev agents | | `KUGETSU_TEMP_DIR` | `~/.local/share/opencode/tool-output` | Temp directory for subagent tool output (useful in headless environments where /tmp is restricted) | +| `KUGETSU_VERBOSITY` | `default` | PM agent verbosity level: `verbose`, `default`, or `quiet` | ### Environment Variables for Agents @@ -255,6 +256,90 @@ kugetsu destroy --base -y **Note**: Destroying base also destroys PM agent since PM depends on base. +### kugetsu delegate `` + +Send a message to the PM agent for task coordination (fire-and-forget): +```bash +kugetsu delegate "work on issue #14" +kugetsu delegate "review PR #92" +``` + +- Non-blocking: returns immediately, runs in background +- PM agent processes the message asynchronously +- Uses `KUGETSU_VERBOSITY` env var to control PM agent output verbosity +- Log output stored in `~/.kugetsu/logs/delegate-.log` + +### kugetsu logs [n] + +Show recent delegation logs: +```bash +kugetsu logs # Show last 10 logs +kugetsu logs 20 # Show last 20 logs +``` + +- Logs are stored in `~/.kugetsu/logs/` +- Automatically deletes logs older than 7 days + +### kugetsu status + +Check if kugetsu is properly initialized: +```bash +kugetsu status +``` + +Output: +- `kugetsu_not_initialized` - No index file +- `base_session_missing` - Base session not found +- `pm_agent_missing` - PM agent not found +- `ok` - Everything is initialized + +### kugetsu doctor [--fix] + +Diagnose and fix kugetsu issues: +```bash +kugetsu doctor # Show diagnostic info +kugetsu doctor --fix # Attempt automatic repairs +``` + +- Checks index file existence +- Validates base and PM agent sessions +- With `--fix`: recreates PM agent if missing +- With `--fix-permissions`: fixes session permissions in opencode database + +### kugetsu notify [list|clear] + +Show or clear notifications from PM agent: +```bash +kugetsu notify list # Show unread notifications (default) +kugetsu notify clear # Mark all as read +``` + +- PM agent writes task completion notifications to `~/.kugetsu/notifications.json` +- Shows timestamp, type, message, and issue ref for each notification + +### kugetsu server + +Manage git server configurations: +```bash +kugetsu server list # List all configured servers +kugetsu server add github https://github.com # Add a server +kugetsu server remove gitlab # Remove a server +kugetsu server default github # Set default server +kugetsu server get github # Get server URL +``` + +### kugetsu queue + +Manage task queue for autonomous PM operation: +```bash +kugetsu queue list # Show queued tasks +kugetsu queue enqueue "task" # Add task to queue +kugetsu queue dequeue # Remove next task from queue +kugetsu queue clear # Clear all queued tasks +``` + +- Queue stored in `~/.kugetsu/queue.json` + ## Workflow Example ```bash diff --git a/skills/kugetsu/scripts/kugetsu b/skills/kugetsu/scripts/kugetsu index f444506..c7ea0f9 100755 --- a/skills/kugetsu/scripts/kugetsu +++ b/skills/kugetsu/scripts/kugetsu @@ -735,7 +735,7 @@ cmd_env() { fi local file="$ENV_DIR/${target}.env" if [ -f "$file" ]; then - sed -i "/^${key}=/d" "$file" + grep -v "^${key}=" "$file" > "$file.tmp" && mv "$file.tmp" "$file" echo "Removed $key from ${target}.env" fi ;; @@ -1106,7 +1106,11 @@ EOF echo "Press Ctrl+C to cancel or wait for session to be created" sleep 2 - opencode + if ! opencode; then + echo "Error: opencode TUI failed to start" >&2 + echo "Please ensure opencode is installed and accessible" >&2 + exit 1 + fi local session_ids=$(opencode session list 2>/dev/null | grep -E '^ses_' | awk '{print $1}' | tail -1) if [ -z "$session_ids" ]; then diff --git a/skills/kugetsu/tests/test-kugetsu.sh b/skills/kugetsu/tests/test-kugetsu.sh deleted file mode 100755 index 2f82ab1..0000000 --- a/skills/kugetsu/tests/test-kugetsu.sh +++ /dev/null @@ -1,277 +0,0 @@ -#!/bin/bash -# kugetsu test suite -# Run with: bash skills/kugetsu/tests/test-kugetsu.sh -# -# Memory management approach: -# - Sequential test execution (no parallel) -# - Cleanup between tests that spawn opencode -# - No hard memory cap (ulimit -v breaks Bun/opencode) -# - If OOM occurs, it is a known failure mode - -set -euo pipefail - -KUGETSU="./skills/kugetsu/scripts/kugetsu" -TEST_SESSION_PREFIX="kugetsu-test-" -PASS=0 -FAIL=0 - -cleanup_sessions() { - for dir in ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}*; do - [ -d "$dir" ] && rm -rf "$dir" 2>/dev/null || true - done -} - -cleanup_opencode() { - pkill -f "opencode.*${TEST_SESSION_PREFIX}" 2>/dev/null || true - pkill -f "kugetsu.*${TEST_SESSION_PREFIX}" 2>/dev/null || true - sleep 0.5 -} - -cleanup() { - cleanup_sessions - cleanup_opencode -} - -pass() { - echo "✅ PASS: $1" - PASS=$((PASS + 1)) -} - -fail() { - echo "❌ FAIL: $1" - FAIL=$((FAIL + 1)) -} - -cleanup - -echo "=== kugetsu Test Suite ===" -echo "" - -# Test 1: Help -echo "--- Test: help ---" -if $KUGETSU help 2>&1 | grep -q "kugetsu - OpenCode Session Manager"; then - pass "help displays usage" -else - fail "help displays usage" -fi -echo "" - -# Test 2: List empty -echo "--- Test: list (empty) ---" -if $KUGETSU list 2>&1 | grep -q "SESSION_ID"; then - pass "list shows header even when empty" -else - fail "list shows header even when empty" -fi -echo "" - -# Test 3: List --all empty -echo "--- Test: list --all (empty) ---" -if $KUGETSU list --all 2>&1 | grep -q "SESSION_ID"; then - pass "list --all shows header even when empty" -else - fail "list --all shows header even when empty" -fi -echo "" - -# Test 4: Start session (quick exit) -echo "--- Test: start session ---" -if timeout 15 bash -c "$KUGETSU start ${TEST_SESSION_PREFIX}start-test 'echo hello'" 2>&1; then - if [ -d ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}start-test ]; then - pass "start creates session directory" - else - fail "start creates session directory" - fi -else - fail "start runs successfully" -fi -echo "" - -# Test 5: List shows only left by default -echo "--- Test: list default filters non-left ---" -if ! $KUGETSU list 2>&1 | grep -q "${TEST_SESSION_PREFIX}start-test"; then - pass "list default hides idle sessions" -else - fail "list default hides idle sessions" -fi -echo "" - -# Test 6: List --all shows all -echo "--- Test: list --all shows all states ---" -if $KUGETSU list --all 2>&1 | grep -q "${TEST_SESSION_PREFIX}start-test"; then - pass "list --all shows all sessions" -else - fail "list --all shows all sessions" -fi -echo "" - -# Test 7: Resume with auto-fill -echo "--- Test: resume auto-fill ---" -mkdir -p ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}resume-test -echo "left" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}resume-test/state -echo "continue this task" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}resume-test/message - -OUTPUT=$(timeout 10 bash -c "$KUGETSU resume ${TEST_SESSION_PREFIX}resume-test" 2>&1 || true) -if echo "$OUTPUT" | grep -q "Auto-filled message: continue this task"; then - pass "resume auto-fills stored message" -else - fail "resume auto-fills stored message" -fi -cleanup -echo "" - -# Test 8: Resume with provided message overrides -echo "--- Test: resume with message overrides ---" -mkdir -p ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}resume-override -echo "left" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}resume-override/state -echo "original message" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}resume-override/message - -OUTPUT=$(timeout 30 bash -c "$KUGETSU resume ${TEST_SESSION_PREFIX}resume-override 'new message'" 2>&1 || true) -if echo "$OUTPUT" | grep -q "new message" && ! echo "$OUTPUT" | grep -q "Auto-filled message"; then - pass "resume uses provided message over auto-fill" -else - fail "resume uses provided message over auto-fill: $OUTPUT" -fi -cleanup -echo "" - -# Test 9: Resume idle session fails -echo "--- Test: resume idle session fails ---" -rm -rf ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}idle-test 2>/dev/null -mkdir -p ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}idle-test -echo "idle" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}idle-test/state - -OUTPUT=$(timeout 5 bash -c "$KUGETSU resume ${TEST_SESSION_PREFIX}idle-test" 2>&1 || true) -if echo "$OUTPUT" | grep -q "cannot be resumed"; then - pass "resume idle session fails with message" -else - echo "DEBUG: $OUTPUT" - fail "resume idle session fails with message" -fi -echo "" - -# Test 10: Resume non-existent session fails -echo "--- Test: resume non-existent session fails ---" -rm -rf ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}nonexistent 2>/dev/null -OUTPUT=$(timeout 5 bash -c "$KUGETSU resume ${TEST_SESSION_PREFIX}nonexistent" 2>&1 || true) -if echo "$OUTPUT" | grep -q "not found"; then - pass "resume non-existent session fails" -else - echo "DEBUG: $OUTPUT" - fail "resume non-existent session fails" -fi -echo "" - -# Test 11: Stop non-used session fails -echo "--- Test: stop non-used session fails ---" -rm -rf ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}notused 2>/dev/null -mkdir -p ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}notused -echo "idle" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}notused/state - -OUTPUT=$(timeout 5 bash -c "$KUGETSU stop ${TEST_SESSION_PREFIX}notused" 2>&1 || true) -if echo "$OUTPUT" | grep -q "not in use"; then - pass "stop non-used session fails" -else - echo "DEBUG: $OUTPUT" - fail "stop non-used session fails" -fi -echo "" - -# Test 12: Start existing left session resumes instead -echo "--- Test: start on left session resumes ---" -mkdir -p ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}left-start -echo "left" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}left-start/state -echo "original task" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}left-start/message - -OUTPUT=$(timeout 10 bash -c "$KUGETSU start ${TEST_SESSION_PREFIX}left-start 'new task'" 2>&1 || true) -if echo "$OUTPUT" | grep -q "Resuming instead"; then - pass "start on left session resumes" -else - fail "start on left session resumes" -fi -cleanup -echo "" - -# ============================================================================ -# FLAKY TESTS - Commented out due to timing/process behavior issues -# ============================================================================ - -# Test: Stop active session (FLAKY - timing dependent) -# echo "--- Test: stop active session (FLAKY) ---" -# ( -# timeout 20 bash -c "$KUGETSU start ${TEST_SESSION_PREFIX}stop-test 'sleep 30'" 2>&1 & -# KUGETSU_PID=$! -# sleep 3 -# -# # Check session is in use -# if ! $KUGETSU list --all 2>&1 | grep -q "${TEST_SESSION_PREFIX}stop-test.*used"; then -# echo "⚠️ SKIP (FLAKY): Could not verify session was used" -# elif timeout 5 bash -c "$KUGETSU stop ${TEST_SESSION_PREFIX}stop-test" 2>&1; then -# if [ "$(cat ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}stop-test/state 2>/dev/null)" = "idle" ]; then -# echo "✅ PASS (FLAKY): stop transitions to idle" -# else -# echo "❌ FAIL (FLAKY): stop does not transition to idle" -# fi -# else -# echo "❌ FAIL (FLAKY): stop command failed" -# fi -# -# wait $KUGETSU_PID 2>/dev/null || true -# ) 2>&1 || true - -# Test: Interrupt session leaves state as left (FLAKY - opencode signal handling) -# echo "--- Test: interrupt session leaves left (FLAKY) ---" -# ( -# bash -c "$KUGETSU start ${TEST_SESSION_PREFIX}interrupt-test 'sleep 30'" 2>&1 & -# KUGETSU_PID=$! -# sleep 3 -# -# # Find and kill opencode process -# OPENCODE_PID=$(pgrep -f "opencode.*${TEST_SESSION_PREFIX}interrupt-test" | head -1 || true) -# if [ -n "$OPENCODE_PID" ]; then -# kill -9 $OPENCODE_PID 2>/dev/null || true -# fi -# -# wait $KUGETSU_PID 2>/dev/null || true -# sleep 1 -# -# STATE=$(cat ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}interrupt-test/state 2>/dev/null || echo "unknown") -# if [ "$STATE" = "left" ]; then -# echo "✅ PASS (FLAKY): interrupt leaves state as left" -# else -# echo "❌ FAIL (FLAKY): interrupt left state=$STATE (expected left)" -# fi -# ) 2>&1 || true - -# Test: Concurrent resume attempts (FLAKY - race condition) -# echo "--- Test: concurrent resume (FLAKY) ---" -# mkdir -p ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}concurrent -# echo "left" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}concurrent/state -# echo "test task" > ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}concurrent/message -# -# ( -# timeout 10 bash -c "$KUGETSU resume ${TEST_SESSION_PREFIX}concurrent" 2>&1 & -# timeout 10 bash -c "$KUGETSU resume ${TEST_SESSION_PREFIX}concurrent" 2>&1 -# ) 2>&1 || true -# -# echo "⚠️ NOTE (FLAKY): This test is informational only - no assertion" -# rm -rf ~/.kugetsu/sessions/${TEST_SESSION_PREFIX}concurrent - -# ============================================================================ -# Cleanup -# ============================================================================ -cleanup - -echo "" -echo "=== Test Summary ===" -echo "Passed: $PASS" -echo "Failed: $FAIL" -echo "" - -if [ $FAIL -eq 0 ]; then - echo "All tests passed!" - exit 0 -else - echo "Some tests failed." - exit 1 -fi -- 2.49.1