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:
125
skills/kugetsu/SKILL.md
Normal file
125
skills/kugetsu/SKILL.md
Normal 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.
|
||||
Reference in New Issue
Block a user