feat: add kugetsu session manager skill

- skills/kugetsu/SKILL.md: Agent skill documentation following agentskills.io spec
- skills/kugetsu/scripts/kugetsu: Shell wrapper for opencode session management
  - Commands: start, list [--all], resume, stop, help
  - State tracking: used → idle (graceful) or left (interrupted)
  - Auto-fill message on resume
  - Confirmation prompt when resuming used session
- skills/kugetsu/scripts/kugetsu-install.sh: Installation script for users

Implements Phase 1 of issue #11 - basic session management layer
for remote agent control without Hermes dependency.
This commit is contained in:
shokollm
2026-03-29 10:50:14 +00:00
parent aba9d5321f
commit 7edb54cd3f
3 changed files with 508 additions and 0 deletions

125
skills/kugetsu/SKILL.md Normal file
View File

@@ -0,0 +1,125 @@
---
name: kugetsu
description: Session manager for opencode CLI. Use when managing long-running opencode sessions, resuming interrupted work, or tracking session state across disconnects. Features state tracking (used/idle/left), auto-fill last message on resume, and safe locking via confirmation prompts.
license: MIT
compatibility: Requires opencode CLI, bash, and filesystem access for session state.
metadata:
author: shoko
version: "1.0"
---
# kugetsu - OpenCode Session Manager
Manages opencode CLI sessions with state tracking and safe resume.
## Installation
### For Human Users
Run once on a new host:
```bash
. skills/kugetsu/scripts/kugetsu-install.sh
```
### For Agents (Self-Install)
Copy the script to your PATH:
```bash
cp skills/kugetsu/scripts/kugetsu ~/.local/bin/kugetsu
chmod +x ~/.local/bin/kugetsu
```
Or source directly when needed:
```bash
. skills/kugetsu/scripts/kugetsu
```
## Session State
| State | Meaning | Resumable? |
|-------|---------|------------|
| `used` | Session is active (process running) | Yes (with confirmation) |
| `idle` | Session ended gracefully | No |
| `left` | Session interrupted/crashed | Yes |
| `invalid` | Session data missing/corrupt | No |
## Session Directory
Sessions are stored in `~/.kugetsu/sessions/<session_id>/`:
- `state` - current state (used/idle/left/invalid)
- `message` - last user message (for auto-fill)
- `pid` - active process PID (when used)
## Commands
### kugetsu start `<session_id>` `<message>`
Start a new session:
```bash
kugetsu start mytask "fix bug #1"
```
- Creates session directory
- Sets state to `used`
- Stores PID and message
- Runs: `opencode run --session <session_id> <message>`
### kugetsu list [--all]
List sessions:
```bash
kugetsu list # Shows only `left` (resumable)
kugetsu list --all # Shows all states
```
### kugetsu resume `<session_id>` [message]
Resume an interrupted session:
```bash
kugetsu resume mytask # Auto-fills last message
kugetsu resume mytask "continue" # Uses provided message
```
- If state is `used`: prompts for confirmation (someone else might be using)
- If state is `idle`: errors (not resumable)
- If state is `left`: proceeds with message
### kugetsu stop `<session_id>`
Stop a session gracefully:
```bash
kugetsu stop mytask
```
- Sends SIGTERM to process
- Sets state to `idle`
### kugetsu help
Show usage help.
## State Transitions
```
start ──────────────► used ──────► idle (stop/SIGTERM)
└──────► left (kill/SIGINT/crash)
```
## Example Workflow
```bash
# Start a long-running task
kugetsu start issue42 "implement feature X"
# ... time passes, connection drops ...
# Check what sessions are resumable
kugetsu list
# Resume with auto-filled message
kugetsu resume issue42
# Later, when done
kugetsu stop issue42
```
## Without kugetsu
If kugetsu is not installed, use opencode directly:
```bash
opencode run --session mytask "task description"
opencode run --continue --session mytask "continue"
opencode session list
```
Tradeoff: No state tracking, no auto-fill, no filtered list, no confirmation prompts.