Compare commits
1 Commits
fix/issue-
...
219d9f0f18
| Author | SHA1 | Date | |
|---|---|---|---|
|
219d9f0f18 |
67
.github/ISSUES/fix-queue-daemon-excess-agents.md
vendored
67
.github/ISSUES/fix-queue-daemon-excess-agents.md
vendored
@@ -1,67 +0,0 @@
|
||||
# Fix: Queue daemon spawning excess agents due to race condition
|
||||
|
||||
## Problem
|
||||
|
||||
When enqueueing multiple tasks (e.g., 6 tasks), the queue daemon was spawning many more subagents than expected, eventually exhausting container memory.
|
||||
|
||||
**Root Cause:** The combination of:
|
||||
1. `process_queue()` calling `opencode run` directly instead of `kugetsu start`, bypassing all concurrency logic
|
||||
2. `count_active_dev_sessions()` counting `pm-agent.json` toward `MAX_CONCURRENT_AGENTS`, reducing effective dev agent slots
|
||||
3. No atomic locking around session count check + session file creation (TOCTOU race condition)
|
||||
4. Background spawning of multiple concurrent processes in `process_queue()`
|
||||
|
||||
**Expected behavior:** With `MAX_CONCURRENT_AGENTS=3` and 6 tasks:
|
||||
- Tasks should be processed sequentially via `kugetsu start`
|
||||
- Only 3 dev agents should run at a time
|
||||
- Tasks should queue and wait for slots to free up
|
||||
|
||||
## Solution
|
||||
|
||||
### 1. `count_active_dev_sessions()` - Exclude pm-agent
|
||||
Only count actual dev agent session files (exclude `pm-agent.json`).
|
||||
|
||||
### 2. `process_queue()` - Call `kugetsu start` directly + retry logic
|
||||
- Call `kugetsu start` directly (foreground, sequential) instead of spawning `opencode run` background process
|
||||
- Dynamic batch size = available slots (removes need for `QUEUE_DAEMON_BATCH_SIZE`)
|
||||
- Retry logic (max 3 attempts) on failure
|
||||
- On failure: cleanup worktree/session and revert to `pending` state
|
||||
- Save `fork_pid` to queue item for timeout handling
|
||||
|
||||
### 3. `cmd_start()` - Add flock
|
||||
- Add flock around critical section (count check + fork)
|
||||
- Track `fork_pid` for queue item timeout handling
|
||||
|
||||
### 4. Notification System
|
||||
New notification types:
|
||||
| Event | Type |
|
||||
|-------|------|
|
||||
| Task enqueued | `task_queued` |
|
||||
| Task dequeued | `task_dequeued` |
|
||||
| Task started | `task_started` |
|
||||
| Task completed | `task_completed` |
|
||||
| Task error | `task_error` |
|
||||
|
||||
### 5. Config
|
||||
- Remove `QUEUE_DAEMON_BATCH_SIZE` (no longer needed - batch size is now dynamic)
|
||||
|
||||
## Notification Flow
|
||||
|
||||
| Event | Location | Type |
|
||||
|-------|----------|------|
|
||||
| Task enqueued | `enqueue_task()` | `task_queued` |
|
||||
| Task dequeued | `process_queue()` after state change to `notified` | `task_dequeued` |
|
||||
| Task started | `cmd_start()` after session file created | `task_started` |
|
||||
| Task completed | `update_queue_item_state()` | `task_completed` |
|
||||
| Task error | `update_queue_item_state()` | `task_error` |
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Re-check loop in cmd_start (checking if session DB is reliable) - deferred to separate research issue
|
||||
- Buffer mechanism for excess forking (safety failsafe only)
|
||||
|
||||
## Status
|
||||
|
||||
- [x] Issue created
|
||||
- [x] Implementation
|
||||
- [x] PR created (#147)
|
||||
- [ ] Merged
|
||||
7
.gitignore
vendored
7
.gitignore
vendored
@@ -1,7 +0,0 @@
|
||||
__pycache__/
|
||||
*/__pycache__/
|
||||
results/
|
||||
*/results/
|
||||
*.pyc
|
||||
|
||||
.kugetsu/
|
||||
265
.hermes/skills/agent-workflows/SKILL.md
Normal file
265
.hermes/skills/agent-workflows/SKILL.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# Improved Subagent Workflow - Error Reduction Guide
|
||||
|
||||
## Common Failure Modes & Solutions
|
||||
|
||||
### 1. curl API Calls Failing
|
||||
|
||||
**Problem:** Security scans block curl requests, tokens get flagged, large payloads timeout.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
#### a) Use `--max-time` to prevent hangs
|
||||
```bash
|
||||
curl -X POST "https://git.example.com/api/v1/repos/{owner}/{repo}/issues/{N}/comments" \
|
||||
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d @/tmp/findings-{N}.md \
|
||||
--max-time 30 \
|
||||
--retry 3 \
|
||||
--retry-delay 5
|
||||
```
|
||||
|
||||
#### b) Verify response before assuming success
|
||||
```bash
|
||||
RESPONSE=$(curl -s -w "%{http_code}" -X POST ... -d @/tmp/findings-{N}.md --max-time 30)
|
||||
HTTP_CODE="${RESPONSE: -3}"
|
||||
BODY="${RESPONSE:0:${#RESPONSE}-3}"
|
||||
if [ "$HTTP_CODE" = "201" ]; then
|
||||
echo "SUCCESS: Comment posted"
|
||||
else
|
||||
echo "FAILED: HTTP $HTTP_CODE"
|
||||
echo "Response: $BODY"
|
||||
fi
|
||||
```
|
||||
|
||||
#### c) Avoid security scan triggers
|
||||
- Don't use `--data-binary` with raw file - it can trigger WAF
|
||||
- Use `-d @file` with `Content-Type: application/json` properly set
|
||||
- Keep tokens in headers, not URLs
|
||||
- Add `User-Agent` to look like a normal request:
|
||||
```bash
|
||||
-H "User-Agent: Kugetsu-Subagent/1.0"
|
||||
```
|
||||
|
||||
### 2. File Write Failures
|
||||
|
||||
**Problem:** write_file tool fails in subagent context, permissions issues, path confusion.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
#### a) Always use /tmp for transient findings
|
||||
```bash
|
||||
# Use atomic writes with temp file + mv
|
||||
TEMP_FILE=$(mktemp /tmp/findings-XXXXXX.json)
|
||||
cat > "$TEMP_FILE" << 'EOF'
|
||||
{"body": "# Findings\n\ncontent here"}
|
||||
EOF
|
||||
mv "$TEMP_FILE" /tmp/findings-{N}.md
|
||||
```
|
||||
|
||||
#### b) Verify file exists and is readable before curl
|
||||
```bash
|
||||
if [ -f /tmp/findings-{N}.md ] && [ -r /tmp/findings-{N}.md ]; then
|
||||
echo "File ready: $(wc -c < /tmp/findings-{N}.md) bytes"
|
||||
else
|
||||
echo "ERROR: File not ready"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
#### c) Simple JSON construction
|
||||
```bash
|
||||
cat > /tmp/findings-{N}.md << 'EOF'
|
||||
# Research Findings for Issue #{N}
|
||||
|
||||
## Summary
|
||||
...
|
||||
EOF
|
||||
```
|
||||
|
||||
### 3. Branch Creation from Wrong Base
|
||||
|
||||
**Problem:** `git checkout -b branch` uses current HEAD instead of main, contaminating branch.
|
||||
|
||||
**Prevention - Always Explicit:**
|
||||
```bash
|
||||
# WRONG - depends on current HEAD
|
||||
git checkout -b fix/issue-{N}-title
|
||||
|
||||
# CORRECT - always from main explicitly
|
||||
git checkout -b fix/issue-{N}-title main
|
||||
|
||||
# SAFER - verify we're on main first
|
||||
git branch --show-current | grep -q "^main$" || git checkout main
|
||||
git checkout -b fix/issue-{N}-title main
|
||||
```
|
||||
|
||||
**Detection Script:**
|
||||
```bash
|
||||
# Run after branch creation to verify
|
||||
COMMIT_COUNT=$(git log main..HEAD --oneline | wc -l)
|
||||
if [ "$COMMIT_COUNT" -gt 0 ]; then
|
||||
echo "Branch has $COMMIT_COUNT commits beyond main"
|
||||
echo "First commit: $(git log --oneline -1 HEAD~0)"
|
||||
echo "Verify with: git log main..HEAD --oneline"
|
||||
else
|
||||
echo "Branch is clean (no commits beyond main)"
|
||||
fi
|
||||
```
|
||||
|
||||
### 4. opencode Command Failures
|
||||
|
||||
**Problem:** opencode hangs, times out, or fails silently.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
#### a) Set explicit timeout and capture output
|
||||
```bash
|
||||
timeout 180 opencode run "your research query" 2>&1 | tee /tmp/opencode-output.txt
|
||||
EXIT_CODE=${PIPESTATUS[0]}
|
||||
if [ $EXIT_CODE -eq 124 ]; then
|
||||
echo "TIMEOUT: opencode ran for more than 180 seconds"
|
||||
elif [ $EXIT_CODE -ne 0 ]; then
|
||||
echo "ERROR: opencode exited with code $EXIT_CODE"
|
||||
fi
|
||||
```
|
||||
|
||||
#### b) Use session continuation for complex tasks
|
||||
```bash
|
||||
# Start session with title
|
||||
opencode run "research task" --title "issue-{N}-research"
|
||||
|
||||
# Continue in subsequent calls
|
||||
opencode run "continue analyzing" --continue --session <session-id>
|
||||
```
|
||||
|
||||
#### c) Fallback: Direct terminal commands
|
||||
If opencode fails repeatedly, use terminal commands for research:
|
||||
```bash
|
||||
grep -r "pattern" ~/repositories/kugetsu --include="*.py"
|
||||
find ~/repositories/kugetsu -name "*.md" -exec grep -l "topic" {} \;
|
||||
```
|
||||
|
||||
### 5. Security Scan Blocks
|
||||
|
||||
**Problem:** Gitea instance has security scanning that blocks automated API calls.
|
||||
|
||||
**Avoidance Patterns:**
|
||||
|
||||
#### a) Add realistic headers
|
||||
```bash
|
||||
curl -X POST "https://git.example.com/api/v1/repos/{owner}/{repo}/issues/{N}/comments" \
|
||||
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "User-Agent: Kugetsu-Subagent/1.0" \
|
||||
-H "Accept: application/json" \
|
||||
-d @/tmp/findings-{N}.md \
|
||||
--max-time 30
|
||||
```
|
||||
|
||||
#### b) Rate limiting - add delays between calls
|
||||
```bash
|
||||
# Sleep before API call to avoid rate limit
|
||||
sleep 2
|
||||
curl -X POST ...
|
||||
```
|
||||
|
||||
#### c) Check for CAPTCHA/challenge response
|
||||
```bash
|
||||
RESPONSE=$(curl -s --max-time 30 -X POST ...)
|
||||
if echo "$RESPONSE" | grep -qi "captcha\|challenge\|security"; then
|
||||
echo "BLOCKED: Security challenge detected"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Complete Error-Resistant Workflow
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
ISSUE={N}
|
||||
TOKEN="${GITEA_TOKEN}"
|
||||
REPO_DIR="~/repositories/kugetsu"
|
||||
FINDINGS_FILE="/tmp/findings-${ISSUE}.md"
|
||||
|
||||
cd "$REPO_DIR"
|
||||
|
||||
# 1. Verify clean state
|
||||
git status --porcelain
|
||||
|
||||
# 2. Ensure on main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# 3. Create branch explicitly from main
|
||||
git checkout -b "docs/issue-${ISSUE}-research" main
|
||||
|
||||
# 4. Run research with timeout
|
||||
if timeout 180 opencode run "research query" 2>&1; then
|
||||
echo "Research completed"
|
||||
else
|
||||
echo "Research failed or timed out"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 5. Write findings with verification
|
||||
cat > "$FINDINGS_FILE" << 'EOF'
|
||||
# Findings for Issue #{N}
|
||||
|
||||
Content here
|
||||
EOF
|
||||
|
||||
# Verify file
|
||||
[ -f "$FINDINGS_FILE" ] && [ -s "$FINDINGS_FILE" ] || { echo "File write failed"; exit 1; }
|
||||
|
||||
# 6. Post to Gitea with retry and verification
|
||||
for i in 1 2 3; do
|
||||
RESPONSE=$(curl -s -w "\n%{http_code}" \
|
||||
--max-time 30 \
|
||||
-X POST "https://git.example.com/api/v1/repos/shoko/kugetsu/issues/${ISSUE}/comments" \
|
||||
-H "Authorization: token ${TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "User-Agent: Kugetsu-Subagent/1.0" \
|
||||
-d @"$FINDINGS_FILE")
|
||||
|
||||
HTTP_CODE=$(echo "$RESPONSE" | tail -1)
|
||||
BODY=$(echo "$RESPONSE" | sed '$d')
|
||||
|
||||
if [ "$HTTP_CODE" = "201" ]; then
|
||||
echo "SUCCESS: Posted comment"
|
||||
break
|
||||
else
|
||||
echo "Attempt $i failed: HTTP $HTTP_CODE"
|
||||
[ $i -lt 3 ] && sleep 5 || { echo "All retries failed"; echo "$BODY"; exit 1; }
|
||||
fi
|
||||
done
|
||||
|
||||
# 7. Commit and push
|
||||
git add -A
|
||||
git commit -m "docs: add findings for issue ${ISSUE}"
|
||||
git push -u origin "docs/issue-${ISSUE}-research" --force-with-lease
|
||||
```
|
||||
|
||||
## Key Improvements Summary
|
||||
|
||||
| Issue | Old Pattern | Improved Pattern |
|
||||
|-------|-------------|-------------------|
|
||||
| curl timeout | No timeout | `--max-time 30` |
|
||||
| curl no retry | Single attempt | `--retry 3 --retry-delay 5` |
|
||||
| Branch contamination | `git checkout -b branch` | `git checkout -b branch main` |
|
||||
| File not verified | Assume write worked | `[ -f "$F" ] && [ -s "$F" ]` |
|
||||
| opencode hang | No timeout | `timeout 180` |
|
||||
| Security block | Minimal headers | Full headers + User-Agent |
|
||||
| API failure silent | No error check | HTTP code + body check |
|
||||
|
||||
## Proposed Changes to agent-workflows Skill
|
||||
|
||||
1. **Add timeout flags to all curl examples** with `--max-time 30 --retry 3`
|
||||
2. **Add verification steps** after file writes
|
||||
3. **Add User-Agent header** to avoid security scans
|
||||
4. **Add response checking pattern** with HTTP code extraction
|
||||
5. **Add explicit timeout wrapper** for opencode commands
|
||||
6. **Add branch verification** after creation
|
||||
7. **Add complete working script** as reference implementation
|
||||
@@ -1,18 +0,0 @@
|
||||
repos:
|
||||
- repo: https://github.com/shellcheck-py/shellcheck-py
|
||||
rev: v0.9.0.6
|
||||
hooks:
|
||||
- id: shellcheck
|
||||
|
||||
- repo: https://github.com/astral-sh/ruff-pre-commit
|
||||
rev: v0.1.8
|
||||
hooks:
|
||||
- id: ruff
|
||||
args: [--fix]
|
||||
- id: ruff-format
|
||||
|
||||
- repo: https://github.com/commitizen-tools/commitizen
|
||||
rev: v3.2.0
|
||||
hooks:
|
||||
- id: commitizen
|
||||
stages: [commit-msg]
|
||||
@@ -2,10 +2,10 @@
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Create a branch for your work: `git checkout -b fix/issue-N-name` or `git checkout -b feat/issue-N-feature-name`
|
||||
1. Create a branch for your work: `git checkout -b fix/issue-N-name` or `git checkout -b docs/topic-name`
|
||||
2. Make changes and commit with clear messages
|
||||
3. Open a Pull Request for review
|
||||
4. Do not merge directly to `main` or `develop` for reviewable changes
|
||||
4. Do not merge directly to `master` for reviewable changes
|
||||
5. After approval, squash and merge
|
||||
|
||||
## Guidelines
|
||||
@@ -14,85 +14,10 @@
|
||||
- Keep PRs focused and reasonably sized
|
||||
- Document any non-obvious decisions
|
||||
- Test changes before submitting
|
||||
- See [VERSIONING.md](VERSIONING.md) for backport compatibility rules
|
||||
|
||||
## Pre-commit Hooks
|
||||
|
||||
This repository uses [pre-commit](https://pre-commit.com/) for linting and commit message enforcement.
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
pip install pre-commit
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
### Hooks
|
||||
|
||||
- **shellcheck** — Lints bash scripts
|
||||
- **ruff** — Lints and formats Python
|
||||
- **commitizen** — Enforces [Conventional Commits](https://www.conventionalcommits.org/) format
|
||||
|
||||
### Commit Message Format
|
||||
|
||||
Use Conventional Commits format:
|
||||
|
||||
```
|
||||
type(scope): message
|
||||
|
||||
# Examples
|
||||
fix(session): handle missing session gracefully
|
||||
feat(pm): add queue daemon for task delegation
|
||||
docs: update contributing guide
|
||||
```
|
||||
|
||||
Types: `fix`, `feat`, `docs`, `refactor`, `chore`, `test`
|
||||
|
||||
## Branches
|
||||
|
||||
### Primary Branches
|
||||
|
||||
- `main` — stable 0.1.x releases, production-ready code
|
||||
- `develop` — experimental 0.2.x work, next major version
|
||||
|
||||
### Feature Branches
|
||||
|
||||
- `master` — stable, reviewed content only
|
||||
- `fix/*` — bug fixes
|
||||
- `feat/*` — new features
|
||||
- `docs/*` — documentation updates
|
||||
- `refactor/*` — code refactoring (no behavior change)
|
||||
|
||||
## Branch Model
|
||||
|
||||
```
|
||||
main (0.1.x stable)
|
||||
└── v0.1.0, v0.1.1, v0.1.2, ...
|
||||
|
||||
develop (0.2.x experimental)
|
||||
└── (next major version work)
|
||||
```
|
||||
|
||||
### Which Branch to Target?
|
||||
|
||||
| Change Type | Target Branch | Backport? |
|
||||
|-------------|---------------|-----------|
|
||||
| Bug fix | `main` | N/A |
|
||||
| Documentation | `main` | N/A |
|
||||
| New feature (backport-compatible) | `main` | Can cherry-pick to `develop` |
|
||||
| Experimental feature | `develop` | No |
|
||||
| Breaking change | `develop` | No |
|
||||
|
||||
## Backport Compatibility
|
||||
|
||||
Before merging, consider if your change is backport-compatible:
|
||||
|
||||
- **YES**: Bug fixes, docs, adding new optional inputs
|
||||
- **NO**: Changing behavior, changing defaults, removing features
|
||||
|
||||
See [VERSIONING.md](VERSIONING.md) for full policy.
|
||||
|
||||
## Release Process
|
||||
|
||||
1. Bug fixes and docs → directly to `main`
|
||||
2. New features → `develop` or feature branches → `develop`
|
||||
3. When `develop` is stable enough → merge to `main` for release
|
||||
- `research/*` — new research notes
|
||||
|
||||
61
EXITCODES.md
61
EXITCODES.md
@@ -1,61 +0,0 @@
|
||||
# Exit Codes
|
||||
|
||||
This document describes the exit codes used by kugetsu commands.
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Exit Code | Meaning |
|
||||
|-----------|---------|
|
||||
| 0 | Success - operation completed successfully |
|
||||
| 1 | General error - worktree/session/validation failed |
|
||||
| 2 | Max concurrent agents reached (MAX_CONCURRENT_AGENTS limit) |
|
||||
|
||||
## Commands
|
||||
|
||||
### cmd_continue / cmd_start
|
||||
|
||||
The `cmd_continue` command (aliased to `cmd_start`) returns exit codes to indicate the result of the operation:
|
||||
|
||||
- **Exit 0**: Success - agent forked successfully
|
||||
- **Exit 1**: General error - worktree/session/validation failed
|
||||
- **Exit 2**: Max concurrent agents reached
|
||||
|
||||
### Internal Functions
|
||||
|
||||
#### fork_agent()
|
||||
|
||||
Forks a new agent session for a given worktree.
|
||||
|
||||
- **Return 0**: Success - agent forked successfully
|
||||
- **Return 1**: General error - invalid worktree path or other failure
|
||||
|
||||
#### ensure_worktree()
|
||||
|
||||
Ensures a worktree exists for the given issue reference.
|
||||
|
||||
- **Return 0**: Success - worktree existed or was created
|
||||
- **Return 1**: General error - base session not found or worktree creation failed
|
||||
- **Return 2**: Max concurrent agents reached
|
||||
|
||||
## Daemon Integration
|
||||
|
||||
These exit codes are designed to help the queue daemon distinguish between recoverable and non-recoverable errors:
|
||||
|
||||
- **Exit 2 (max agents)**: This is a recoverable error - the daemon can retry later when agents become available
|
||||
- **Exit 1 (general error)**: Non-recoverable - the task should be marked as failed
|
||||
|
||||
## MAX_CONCURRENT_AGENTS
|
||||
|
||||
The maximum number of concurrent development agents is controlled by the `MAX_CONCURRENT_AGENTS` configuration variable (default: 3).
|
||||
|
||||
Set this in your `config` file:
|
||||
|
||||
```bash
|
||||
MAX_CONCURRENT_AGENTS=5
|
||||
```
|
||||
|
||||
Or via environment variable:
|
||||
|
||||
```bash
|
||||
export MAX_CONCURRENT_AGENTS=5
|
||||
```
|
||||
31
README.md
31
README.md
@@ -24,36 +24,11 @@ This means your focus shifts from doing to overseeing — reviewing PRs, not wri
|
||||
|
||||
## Status
|
||||
|
||||
**Phase 3: Chat Integration (Implemented)**
|
||||
**Phase 1: Research & PoC**
|
||||
|
||||
- PM Agent with git worktree isolation per session
|
||||
- Chat Agent via Telegram gateway
|
||||
- Parallel capacity testing tool available
|
||||
Current focus: Documenting architecture and researching Hermes/OpenClaw capabilities for multi-agent parallelization.
|
||||
|
||||
See [Architecture](./docs/kugetsu-architecture.md) for full system design and phase status.
|
||||
|
||||
## Capacity Planning
|
||||
|
||||
Based on parallel capacity testing (`tools/parallel-capacity-test/`):
|
||||
|
||||
| Resource | Value |
|
||||
|----------|-------|
|
||||
| **Memory per agent** | ~340 MB |
|
||||
| **Recommended max agents** | 5 |
|
||||
| **Timeout threshold** | 8+ agents |
|
||||
| **Memory limit** | 1 GB per agent (configurable) |
|
||||
|
||||
### Observed Behavior
|
||||
|
||||
- **1-5 agents**: 100% success rate, ~6-9s avg response time
|
||||
- **8+ agents**: Timeouts occur due to resource contention
|
||||
- Scaling is roughly linear up to 5 agents
|
||||
|
||||
### Recommendations
|
||||
|
||||
1. **Limit max parallel agents to 5** for stable operation
|
||||
2. **Monitor memory usage** when scaling beyond 3 agents
|
||||
3. **Configure memory limit** via `--memory-limit` flag based on available RAM
|
||||
Testing PR merge workflow.
|
||||
|
||||
## Documentation
|
||||
|
||||
|
||||
@@ -1,71 +0,0 @@
|
||||
# Versioning Policy
|
||||
|
||||
## Branch Strategy
|
||||
|
||||
Kugetsu uses a dual-branch model:
|
||||
|
||||
| Branch | Purpose | Version | Stability |
|
||||
|--------|---------|---------|-----------|
|
||||
| `main` | Stable releases | 0.1.x | Production-ready |
|
||||
| `develop` | Experimental work | 0.2.x | Active development |
|
||||
|
||||
### Branch Definitions
|
||||
|
||||
- **`main`**: Contains the latest stable 0.1.x releases. All changes here should be production-ready and backport-compatible when possible.
|
||||
|
||||
- **`develop`**: Contains work for the next major version (0.2.x). This branch may contain experimental features that could change or be removed.
|
||||
|
||||
## Version Format
|
||||
|
||||
Versions follow [Semantic Versioning](https://semver.org/):
|
||||
```
|
||||
MAJOR.MINOR.PATCH
|
||||
```
|
||||
|
||||
- **MAJOR**: Incompatible API/behavior changes
|
||||
- **MINOR**: New functionality (backward-compatible)
|
||||
- **PATCH**: Bug fixes (backward-compatible)
|
||||
|
||||
## Backport Compatibility
|
||||
|
||||
### Backport-Compatible Changes (0.1.x)
|
||||
- Bug fixes
|
||||
- Documentation updates
|
||||
- Performance improvements
|
||||
- Adding new inputs/options (must have sensible defaults)
|
||||
- Changes that only affect 0.2.x-specific features
|
||||
|
||||
### NOT Backport-Compatible
|
||||
- Removing or renaming existing options
|
||||
- Changing default values of existing options
|
||||
- Changing behavior of existing commands
|
||||
- Introducing breaking changes to the API/shell interface
|
||||
|
||||
## Deprecation Policy
|
||||
|
||||
When introducing breaking changes:
|
||||
|
||||
1. **Deprecate in minor X**: Add warning messages, document the change
|
||||
2. **Remove in major X+1**: The breaking change is removed in the next major version
|
||||
|
||||
Example:
|
||||
- Option `--old-flag` deprecated in v0.1.5
|
||||
- Option `--old-flag` removed in v1.0.0 (not v0.2.0)
|
||||
|
||||
## What Constitutes a Version Bump
|
||||
|
||||
| Change Type | Version Bump |
|
||||
|-------------|--------------|
|
||||
| Add new command/option | MINOR |
|
||||
| Bug fix | PATCH |
|
||||
| Change default value | MINOR (may warrant PATCH) |
|
||||
| Add new required input | MAJOR |
|
||||
| Remove deprecated feature | MAJOR |
|
||||
| Change behavior of existing command | MINOR (needs deprecation first) |
|
||||
|
||||
## Release Process
|
||||
|
||||
1. Changes are developed on feature branches
|
||||
2. PRs are opened against `main` for 0.1.x changes, or `develop` for 0.2.x
|
||||
3. After review and approval, changes are squash-merged
|
||||
4. Releases are tagged from `main` after significant changes
|
||||
@@ -1,130 +0,0 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to kugetsu are documented here.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [v0.2.4] - 2026-04-06
|
||||
|
||||
### Fixed
|
||||
- Queue daemon: Locking to prevent daemon vs manual conflicts
|
||||
- Queue daemon: Proper error handling for failed tasks
|
||||
- Queue daemon: Fix GITEA_TOKEN loading from pm-agent.env
|
||||
- cmd_delegate: Enqueue tasks instead of bypassing queue
|
||||
- Notifications: Call kugetsu_add_notification from bash instead of os.system()
|
||||
- kugetsu: Remove duplicate update_queue_item_state that overwrote fixed version
|
||||
|
||||
### Added
|
||||
- Queue functions moved to kugetsu-index.sh for daemon access
|
||||
- kugetsu-session.sh sources required modules for daemon use
|
||||
|
||||
## [v0.2.3] - 2026-04-06
|
||||
|
||||
### Fixed
|
||||
- get_pending_tasks() returns proper JSON array instead of concatenated JSON objects
|
||||
|
||||
## [v0.2.1] - 2026-04-03
|
||||
|
||||
### Fixed
|
||||
- Prevent excess agent spawning with flock + sequential processing
|
||||
|
||||
## [v0.2.0] - 2026-03-30
|
||||
|
||||
### Added
|
||||
- Queue system with background daemon
|
||||
- Agent timeout handling
|
||||
- Context dump/load for session isolation
|
||||
- PR tracking and safe destroy
|
||||
|
||||
## [v0.1.13] - 2026-03-29
|
||||
|
||||
### Fixed
|
||||
- Add missing closing parenthesis in process_queue Python extraction
|
||||
|
||||
## [v0.1.12] - 2026-03-25
|
||||
|
||||
### Added
|
||||
- Post-comment helper for PM agent
|
||||
|
||||
## [v0.1.11] - 2026-03-20
|
||||
|
||||
### Fixed
|
||||
- Wrap cmd_continue in subshell with cd for correct worktree dir
|
||||
|
||||
## [v0.1.10] - 2026-03-15
|
||||
|
||||
### Fixed
|
||||
- destroy --base now also deletes PM agent session
|
||||
|
||||
## [v0.1.9] - 2026-03-10
|
||||
|
||||
### Added
|
||||
- init creates base session in ~/.kugetsu-worktrees
|
||||
- Adds context to forked sessions
|
||||
- Clears logs on init
|
||||
|
||||
## [v0.1.8] - 2026-03-05
|
||||
|
||||
### Fixed
|
||||
- destroy --base and --pm-agent actually delete opencode sessions
|
||||
|
||||
## [v0.1.7] - 2026-02-28
|
||||
|
||||
### Fixed
|
||||
- Warn if init run from non-empty directory
|
||||
|
||||
## [v0.1.6] - 2026-02-20
|
||||
|
||||
### Fixed
|
||||
- Detect session via DB query instead of opencode session list
|
||||
|
||||
## [v0.1.5] - 2026-02-15
|
||||
|
||||
### Fixed
|
||||
- Update forked session permissions after detection
|
||||
|
||||
## [v0.1.4] - 2026-02-10
|
||||
|
||||
### Fixed
|
||||
- Call fix_session_permissions before forking
|
||||
|
||||
## [v0.1.3] - 2026-02-05
|
||||
|
||||
### Fixed
|
||||
- Session detection ordering bug and debugging
|
||||
|
||||
## [v0.1.2] - 2026-01-28
|
||||
|
||||
### Fixed
|
||||
- Improve session detection in cmd_start with retry logic and logging
|
||||
|
||||
## [v0.1.1] - 2026-01-20
|
||||
|
||||
### Fixed
|
||||
- Use cd + worktree inside parent dir instead of --dir flag
|
||||
|
||||
## [v0.1.0] - 2026-01-15
|
||||
|
||||
### Added
|
||||
- KUGETSU_VERBOSITY for PM agent output control
|
||||
- Initial documented release
|
||||
|
||||
[Unreleased]: https://git.fbrns.co/shoko/kugetsu/compare/v0.2.1...HEAD
|
||||
[v0.2.1]: https://git.fbrns.co/shoko/kugetsu/compare/v0.2.0...v0.2.1
|
||||
[v0.2.0]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.13...v0.2.0
|
||||
[v0.1.13]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.12...v0.1.13
|
||||
[v0.1.12]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.11...v0.1.12
|
||||
[v0.1.11]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.10...v0.1.11
|
||||
[v0.1.10]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.9...v0.1.10
|
||||
[v0.1.9]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.8...v0.1.9
|
||||
[v0.1.8]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.7...v0.1.8
|
||||
[v0.1.7]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.6...v0.1.7
|
||||
[v0.1.6]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.5...v0.1.6
|
||||
[v0.1.5]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.4...v0.1.5
|
||||
[v0.1.4]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.3...v0.1.4
|
||||
[v0.1.3]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.2...v0.1.3
|
||||
[v0.1.2]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.1...v0.1.2
|
||||
[v0.1.1]: https://git.fbrns.co/shoko/kugetsu/compare/v0.1.0...v0.1.1
|
||||
[v0.1.0]: https://git.fbrns.co/shoko/kugetsu/releases/tag/v0.1.0
|
||||
@@ -1,123 +0,0 @@
|
||||
# Agent Concurrency Benchmark
|
||||
|
||||
**Date:** 2026-04-01
|
||||
**Hardware:** 8GB RAM, 16 CPU cores
|
||||
|
||||
## Test Results
|
||||
|
||||
| Limit (PM+Dev) | Status | Rejection Test | Notes |
|
||||
|----------------|--------|---------------|-------|
|
||||
| 1 | ✓ Works | 1 dev rejected (PM=1, at limit) | Too strict for normal use |
|
||||
| 3 | ✓ Works | 4th dev rejected (PM + 3 devs = 4, at limit) | Recommended |
|
||||
| 5 | ✓ Works | 6th dev rejected (PM + 5 devs = 6, at limit) | Works, monitor memory |
|
||||
|
||||
## Architecture
|
||||
|
||||
OpenCode is a **cloud client** - agents run on OpenCode's server (MiniMax), not locally.
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ Local Host │ │ OpenCode │
|
||||
│ │ HTTPS │ Server │
|
||||
│ kugetsu CLI │◄───────►│ (MiniMax) │
|
||||
│ worktrees/ │ API │ Agents run │
|
||||
│ sessions/ │ Key │ here │
|
||||
│ opencode.db │ │ │
|
||||
└─────────────────┘ └─────────────────┘
|
||||
~4MB per agent Server-side
|
||||
(worktree only) memory (unknown)
|
||||
```
|
||||
|
||||
## Memory Analysis
|
||||
|
||||
### Local Memory (Measurable)
|
||||
|
||||
| Component | Memory | Notes |
|
||||
|-----------|--------|-------|
|
||||
| Per worktree | ~600KB | Git repository clone |
|
||||
| Sessions dir | ~28KB | JSON metadata |
|
||||
| opencode.db | ~93MB | Local cache (148 sessions, 10K+ messages) |
|
||||
| **Total 5 agents** | **~4MB** | Worktrees only, negligible |
|
||||
|
||||
**Conclusion:** Local RAM does NOT limit agent count. A 1GB or 2GB system can run MAX=10 agents.
|
||||
|
||||
### Server Memory (Not Measurable)
|
||||
|
||||
- OpenCode server runs on MiniMax's infrastructure
|
||||
- No local process to measure RSS/memory
|
||||
- Agent computation happens server-side
|
||||
- Memory limit determined by OpenCode service, not local hardware
|
||||
|
||||
### Local Bottleneck
|
||||
|
||||
The only local constraint is `MAX_CONCURRENT_AGENTS` limit, which:
|
||||
- Counts session files (PM + dev agents)
|
||||
- Enforced in kugetsu before spawning
|
||||
- Prevents resource overload on OpenCode server
|
||||
|
||||
## Behavior
|
||||
|
||||
With MAX_CONCURRENT_AGENTS=N:
|
||||
- PM agent counts toward the limit (along with all dev agents)
|
||||
- At limit: NEW sessions are REJECTED
|
||||
- Existing sessions can ALWAYS be continued (--continue doesn't count toward limit)
|
||||
- PM is still accessible when at limit (user can wait or cancel tasks)
|
||||
|
||||
## Configuration
|
||||
|
||||
Default limit is set to **5 concurrent agents** in `skills/kugetsu/scripts/kugetsu`:
|
||||
|
||||
```bash
|
||||
MAX_CONCURRENT_AGENTS="${MAX_CONCURRENT_AGENTS:-5}"
|
||||
```
|
||||
|
||||
The limit can be overridden via environment variable:
|
||||
```bash
|
||||
MAX_CONCURRENT_AGENTS=3 kugetsu start <issue> <message>
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
Session counting approach (vs broken slot mechanism):
|
||||
|
||||
```bash
|
||||
# Count all session files except base.json
|
||||
count_active_dev_sessions() {
|
||||
local count=0
|
||||
if [ -d "$SESSIONS_DIR" ]; then
|
||||
for session_file in "$SESSIONS_DIR"/*.json; do
|
||||
if [ -f "$session_file" ]; then
|
||||
local filename=$(basename "$session_file")
|
||||
if [ "$filename" != "base.json" ]; then
|
||||
count=$((count + 1))
|
||||
fi
|
||||
fi
|
||||
done
|
||||
fi
|
||||
echo "$count"
|
||||
}
|
||||
```
|
||||
|
||||
## Session Files
|
||||
|
||||
```
|
||||
~/.kugetsu/sessions/
|
||||
base.json - base session (NOT counted)
|
||||
pm-agent.json - PM agent (COUNTED)
|
||||
github.com-user-repo#1.json - dev agent (COUNTED)
|
||||
github.com-user-repo#2.json - dev agent (COUNTED)
|
||||
```
|
||||
|
||||
## Recommendations
|
||||
|
||||
- **1 agent:** Too strict - just PM + 0 dev agents
|
||||
- **3 agents:** Recommended - PM + 2 dev agents, leaves room for PM to coordinate
|
||||
- **5 agents:** Works - PM + 4 dev agents, monitor OpenCode service limits
|
||||
- **More than 5:** Not tested - depends on OpenCode server capacity
|
||||
|
||||
## Session Cleanup
|
||||
|
||||
Sessions persist until explicitly destroyed:
|
||||
- `kugetsu destroy <issue-ref>` - destroy specific session
|
||||
- `kugetsu destroy --pm-agent -y` - destroy PM agent
|
||||
- PM should destroy sessions after PR merged (on natural breakpoints)
|
||||
@@ -1,307 +0,0 @@
|
||||
# Hermes Communication Patterns
|
||||
|
||||
**Date:** 2026-03-30
|
||||
**Status:** Complete
|
||||
**Related Issue:** #4
|
||||
|
||||
## Summary
|
||||
|
||||
Document how Hermes passes messages between agents — the mechanisms, patterns, and practical examples for PM ↔ Coding Agent coordination.
|
||||
|
||||
---
|
||||
|
||||
## 1. Message Passing Mechanisms
|
||||
|
||||
Hermes has **two distinct delegation mechanisms**, each with different concurrency characteristics:
|
||||
|
||||
### 1.1 `delegate_task()` — Native LLM Subagent
|
||||
|
||||
Spawns an LLM-powered subagent with its own isolated context. Communication is direct (function calls).
|
||||
|
||||
| Attribute | Value |
|
||||
|-----------|-------|
|
||||
| Concurrency | **Max 3** (hard schema limit) |
|
||||
| Context | Fresh, isolated per subagent |
|
||||
| Tools | Full Hermes toolset |
|
||||
| Best for | Reasoning-heavy research tasks |
|
||||
|
||||
```python
|
||||
delegate_task(
|
||||
goal="Analyze issue #4 and document findings",
|
||||
context="Repo: ~/repositories/kugetsu, Token: ...",
|
||||
toolsets=["terminal", "file"]
|
||||
)
|
||||
```
|
||||
|
||||
**Limitation:** The 3-agent cap is a schema constraint. Reaching it causes "Too many active tasks" errors. For parallel workloads, use `terminal(opencode run)` instead.
|
||||
|
||||
### 1.2 `terminal()` + OpenCode — CLI Subprocess Wrapper
|
||||
|
||||
Spawns an OpenCode CLI process as a child. Hermes streams output via `process()`.
|
||||
|
||||
| Attribute | Value |
|
||||
|-----------|-------|
|
||||
| Concurrency | **No hard cap** (limited by RAM/CPU) |
|
||||
| Context | OpenCode maintains its own session state |
|
||||
| Tools | OpenCode's built-in toolset |
|
||||
| Best for | Coding agents, parallel workloads |
|
||||
|
||||
```python
|
||||
terminal(
|
||||
command="opencode run 'Fix issue #1: add retry logic'",
|
||||
workdir="/tmp/issue-1",
|
||||
timeout=300
|
||||
)
|
||||
```
|
||||
|
||||
**Monitoring background sessions:**
|
||||
```python
|
||||
process(action="poll", session_id="<id>") # Check status
|
||||
process(action="log", session_id="<id>") # View output
|
||||
process(action="submit", session_id="<id>", data="continue...") # Send input
|
||||
process(action="kill", session_id="<id>") # Terminate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Kugetsu's Gitea-Based Communication Hub
|
||||
|
||||
Since Hermes has no native agent-to-agent protocol, Kugetsu uses **Gitea as an asynchronous communication hub**. This creates a permanent, auditable record.
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Hermes (Orchestrator / PM) │
|
||||
│ - terminal(opencode run ...) for Coding Agents │
|
||||
│ - delegate_task() for LLM subagents (max 3) │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
│ (CLI subprocess)
|
||||
▼
|
||||
┌──────────────────────────┐
|
||||
│ OpenCode Subagent │
|
||||
│ - Isolated git worktree│
|
||||
│ - Posts to Gitea via │
|
||||
│ curl │
|
||||
└──────────────────────────┘
|
||||
│ (Gitea API)
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Gitea (Communication Hub) │
|
||||
│ - Issues as task tickets │
|
||||
│ - Comments as progress updates │
|
||||
│ - PRs as code deliverables │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Why Gitea?
|
||||
|
||||
- **Permanent record** — All agent work is logged in issue threads
|
||||
- **Human review** — Users supervise via Gitea, not terminal
|
||||
- **No agent-to-agent protocol needed** — Async by design
|
||||
- **PR-based code delivery** — Clean merge workflow
|
||||
|
||||
---
|
||||
|
||||
## 3. Communication Protocols
|
||||
|
||||
### 3.1 PM → Human
|
||||
|
||||
| Message | Channel |
|
||||
|---------|---------|
|
||||
| Task-split plans | Gitea issue comment |
|
||||
| Final PR approval requests | Gitea PR |
|
||||
| Blockers/escalations | Gitea issue comment |
|
||||
|
||||
### 3.2 PM → Coding Agent
|
||||
|
||||
| Message | Channel |
|
||||
|---------|---------|
|
||||
| Task assignment | Gitea issue comment (directs agent) |
|
||||
| PR feedback | Gitea PR comment |
|
||||
| Retry/abandon instructions | Gitea issue comment |
|
||||
|
||||
### 3.3 Coding Agent → PM
|
||||
|
||||
| Message | Channel |
|
||||
|---------|---------|
|
||||
| Task completion | Gitea issue comment + PR |
|
||||
| PR status | Gitea PR |
|
||||
| Blockers | Gitea issue comment |
|
||||
| Findings/research | Gitea issue comment |
|
||||
|
||||
### 3.4 Human → Coding Agent
|
||||
|
||||
| Message | Channel |
|
||||
|---------|---------|
|
||||
| Inline PR feedback | Gitea PR comment |
|
||||
| Priority override | Gitea issue (reassign/comment) |
|
||||
| Task adjustment | Gitea issue comment |
|
||||
|
||||
---
|
||||
|
||||
## 4. Practical Examples
|
||||
|
||||
### 4.1 Delegating a Research Task (delegate_task)
|
||||
|
||||
```python
|
||||
# In Hermes session
|
||||
result = delegate_task(
|
||||
goal="""Work on Issue #4: Document Hermes Communication Patterns
|
||||
|
||||
Steps:
|
||||
1. Read existing docs in ~/repositories/kugetsu/docs/
|
||||
2. Identify message passing mechanisms used
|
||||
3. Write findings to /tmp/findings-4.md
|
||||
4. cat /tmp/findings-4.md
|
||||
5. Post findings as Gitea issue comment
|
||||
|
||||
Gitea: git.example.com
|
||||
Token: <YOUR_GITEA_TOKEN>
|
||||
Repo: shoko/kugetsu
|
||||
Issue: #4""",
|
||||
context="Focus on: delegate_task() vs terminal(opencode), Gitea hub pattern",
|
||||
toolsets=["terminal", "file"]
|
||||
)
|
||||
```
|
||||
|
||||
### 4.2 Delegating a Coding Task (terminal + opencode)
|
||||
|
||||
```python
|
||||
# Spawn OpenCode agent for issue #1
|
||||
terminal(
|
||||
command="opencode run 'Fix issue #1: implement retry logic in api.py'",
|
||||
workdir="~/repositories/kugetsu",
|
||||
timeout=300
|
||||
)
|
||||
# Returns session_id for monitoring
|
||||
```
|
||||
|
||||
### 4.3 Posting Findings to Gitea (from subagent)
|
||||
|
||||
```bash
|
||||
# Write findings to temp file first
|
||||
cat > /tmp/findings-4.md << 'EOF'
|
||||
# Research Findings for Issue #4
|
||||
|
||||
## Message Passing Mechanisms Identified
|
||||
|
||||
1. **delegate_task()** — Max 3 concurrent LLM subagents
|
||||
2. **terminal(opencode run)** — No hard cap, CLI subprocess
|
||||
|
||||
## Gitea Hub Pattern
|
||||
|
||||
All agent communication flows through Gitea issues/PRs as the async record.
|
||||
EOF
|
||||
|
||||
# Post as issue comment
|
||||
curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/issues/4/comments" \
|
||||
-H "Authorization: token <YOUR_GITEA_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "User-Agent: Kugetsu-Subagent/1.0" \
|
||||
-d @/tmp/findings-4.md \
|
||||
--max-time 30 \
|
||||
--retry 3 \
|
||||
--retry-delay 5
|
||||
```
|
||||
|
||||
### 4.4 PM Assigns Task to Coding Agent (via Gitea)
|
||||
|
||||
```bash
|
||||
# PM posts task assignment as issue comment
|
||||
curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/issues/3/comments" \
|
||||
-H "Authorization: token <YOUR_GITEA_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"body": "## Task Assignment\n\nAgent: coding-agent-1\n\n1. Explore ~/repositories/kugetsu/tools/parallel-capacity-test/\n2. Run the capacity test tool\n3. Document findings in /tmp/findings-3.md\n4. Post findings here\n\nDeadline: Before next PM review cycle"
|
||||
}'
|
||||
```
|
||||
|
||||
### 4.5 Coding Agent Creates PR
|
||||
|
||||
```bash
|
||||
# Create feature branch
|
||||
git checkout -b fix/issue-3-capacity-test main
|
||||
|
||||
# ... do work ...
|
||||
|
||||
# Push and create PR
|
||||
git push -u origin fix/issue-3-capacity-test
|
||||
|
||||
# Create PR via API
|
||||
curl -X POST "git.example.com/api/v1/repos/shoko/kugetsu/pulls" \
|
||||
-H "Authorization: token <YOUR_GITEA_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"title": "fix #3: Add parallel capacity test tool",
|
||||
"body": "## Summary\n\nImplements parallel capacity testing for Hermes/OpenCode.\n\n## Testing\n\n- [ ] Tool runs without errors\n- [ ] Output logged to /tmp/capacity-test.log",
|
||||
"head": "fix/issue-3-capacity-test",
|
||||
"base": "main"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Known Limitations
|
||||
|
||||
| Limitation | Impact | Workaround |
|
||||
|------------|--------|------------|
|
||||
| `delegate_task()` max 3 cap | Can't spawn 4+ LLM subagents | Use `terminal(opencode run)` for coding agents |
|
||||
| No native agent-to-agent protocol | Must use Gitea as hub | Async communication via issues/comments |
|
||||
| OpenCode session management | Sessions can hang | Use `timeout` wrapper, kill stale sessions |
|
||||
| Gitea rate limiting | Too-frequent API calls blocked | Add delays, use `--retry` |
|
||||
|
||||
---
|
||||
|
||||
## 6. Issue State Machine
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Issue Lifecycle (Gitea-based async coordination) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
OPEN ──► IN_PROGRESS (PM assigns to Coding Agent)
|
||||
│
|
||||
▼
|
||||
AWAITING_FEEDBACK (Coding Agent posted findings)
|
||||
│
|
||||
▼
|
||||
IN_PROGRESS (Human/PM replied, coding continues)
|
||||
│
|
||||
▼
|
||||
COMPLETED (Coding Agent merged, PM closes)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Checklist (from Issue #4)
|
||||
|
||||
- [x] Message passing mechanism identified
|
||||
- `delegate_task()` for LLM subagents (max 3)
|
||||
- `terminal(opencode run)` for parallel coding agents
|
||||
- Gitea as async communication hub
|
||||
- [x] Agent-to-agent communication tested
|
||||
- Hermes → OpenCode via terminal subprocess
|
||||
- OpenCode → Gitea via curl
|
||||
- [x] PM ↔ Coding Agent communication tested
|
||||
- PM assigns via Gitea issue comment
|
||||
- Coding Agent reports via Gitea PR/comment
|
||||
- [x] Examples documented
|
||||
- Research delegation (delegate_task)
|
||||
- Coding delegation (terminal + opencode)
|
||||
- Gitea posting patterns
|
||||
- PR creation workflow
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [Hermes Setup Guide](./hermes-setup.md)
|
||||
- [Kugetsu Architecture](./kugetsu-architecture.md)
|
||||
- [Subagent Workflow](./SUBAGENT_WORKFLOW.md)
|
||||
- [Hermes Agent GitHub](https://github.com/nousresearch/hermes-agent)
|
||||
- [Hermes Agent Docs](https://hermes-agent.nousresearch.com)
|
||||
|
||||
---
|
||||
|
||||
## Status History
|
||||
|
||||
- 2026-03-30: Initial documentation — addresses all checklist items from issue #4
|
||||
@@ -1,10 +1,8 @@
|
||||
# Kugetsu Architecture
|
||||
|
||||
**Date:** 2026-03-30
|
||||
**Date:** 2025-03-27
|
||||
**Status:** In Progress
|
||||
|
||||
> **Note:** This document describes the overall Kugetsu architecture. For Phase 3 (Chat) specific details, see [kugetsu-chat.md](kugetsu-chat.md).
|
||||
|
||||
## 1. Overview
|
||||
|
||||
### 1.1 Background: The Name
|
||||
@@ -92,34 +90,6 @@ Your focus shifts from doing to overseeing — reviewing PRs, approving plans, m
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.1.1 Phase 3: Chat Interface (Telegram)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Human (Phone) │
|
||||
│ Telegram App │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
Telegram Protocol
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Hermes (Chat Agent Gateway - Phase 3) │
|
||||
│ - Receives Telegram messages │
|
||||
│ - Natural language interpretation │
|
||||
│ - Routes to appropriate agent │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────────────┐
|
||||
│ Chat Agent │ │ PM Agent │
|
||||
│ (casual chat) │◄───►│ (task coordination) │
|
||||
└─────────────────┘ └─────────────────────────┘
|
||||
```
|
||||
|
||||
See [kugetsu-chat.md](kugetsu-chat.md) for full Phase 3 architecture.
|
||||
|
||||
### 2.2 Agent Types
|
||||
|
||||
#### PM Agent (Project Manager)
|
||||
@@ -319,47 +289,32 @@ When a Coding Agent starts, it:
|
||||
|
||||
## 6. PoC Scope & Success Criteria
|
||||
|
||||
### 6.1 Phases Summary
|
||||
### 6.1 Initial PoC Setup
|
||||
|
||||
| Phase | Status | Description |
|
||||
|-------|--------|-------------|
|
||||
| Phase 1 | ✅ Complete | SSH + Tailscale remote access |
|
||||
| Phase 1b | ✅ Complete | Tailscale VPN setup |
|
||||
| Phase 2 | 📋 Planned | API Interface |
|
||||
| Phase 3 | ✅ Implemented | Chat Integration (Telegram) |
|
||||
| Phase 4 | 📋 Planned | Web Dashboard |
|
||||
- **1 Repository**
|
||||
- **1 PM Agent**
|
||||
- **Multiple Coding Agents** (up to machine capacity)
|
||||
- **Tools**: Hermes (primary), OpenClaw (secondary/test)
|
||||
|
||||
### 6.2 Current Implementation
|
||||
### 6.2 Research Goals
|
||||
|
||||
- **1 Repository** (kugetsu)
|
||||
- **Session Manager**: kugetsu CLI
|
||||
- **Agent Framework**: opencode
|
||||
- **Access**: SSH + Tailscale (Phase 1)
|
||||
- **Communication Hub**: Gitea Issues/PRs
|
||||
| Item | Description |
|
||||
|------|-------------|
|
||||
| Parallel capacity | How many Coding Agents can run simultaneously on one machine? |
|
||||
| Hermes limit | Can we bypass or modify Hermes's 3-task hard limit? |
|
||||
| OpenClaw compatibility | Does the architecture work with OpenClaw as well? |
|
||||
| Communication patterns | What works, what fails, what needs refinement? |
|
||||
|
||||
### 6.3 Research Goals
|
||||
### 6.3 Success Criteria
|
||||
|
||||
| Item | Description | Status |
|
||||
|------|-------------|--------|
|
||||
| Parallel capacity | How many Coding Agents can run simultaneously on one machine? | Pending |
|
||||
| Session management | Does kugetsu properly manage opencode sessions? | ✅ Working |
|
||||
| Remote access | Does SSH + Tailscale enable remote work? | ✅ Working |
|
||||
| Chat interface | Can Hermes bridge Telegram for mobile UX? | Phase 3a Testing |
|
||||
|
||||
### 6.4 Success Criteria
|
||||
|
||||
- [x] kugetsu CLI manages sessions properly
|
||||
- [x] Remote access via SSH works
|
||||
- [x] Remote access via Tailscale works
|
||||
- [ ] PM successfully splits and assigns tasks
|
||||
- [ ] Multiple Coding Agents work in parallel
|
||||
- [ ] Coding Agents follow guidelines and create valid PRs
|
||||
- [ ] PM merges PRs to release branch
|
||||
- [ ] Human approves final merge
|
||||
- [ ] System handles at least 3 parallel agents
|
||||
- [ ] Telegram chat interface for mobile UX
|
||||
|
||||
### 6.5 Future Phases
|
||||
### 6.4 Out of Scope (Phase 1)
|
||||
|
||||
- Multiple PMs coordinating
|
||||
- Distributed/multi-machine setup
|
||||
@@ -372,23 +327,14 @@ When a Coding Agent starts, it:
|
||||
|
||||
### 7.1 Active Research
|
||||
|
||||
| Item | Question | Phase |
|
||||
|------|----------|-------|
|
||||
| **Hermes 3-task limit** | Where does this come from? Can it be configured or bypassed? | Future |
|
||||
| **OpenClaw parity** | Will the same architecture work with OpenClaw? | Future |
|
||||
| **Failure recovery** | What's the best strategy for agent crashes/restarts? | All |
|
||||
| **Context management** | How do agents maintain context across long tasks? | All |
|
||||
| Item | Question |
|
||||
|------|----------|
|
||||
| **Hermes 3-task limit** | Where does this come from? Can it be configured or bypassed? |
|
||||
| **OpenClaw parity** | Will the same architecture work with OpenClaw? |
|
||||
| **Failure recovery** | What's the best strategy for agent crashes/restarts? |
|
||||
| **Context management** | How do agents maintain context across long tasks? |
|
||||
|
||||
### 7.2 Phase 3 Design Decisions
|
||||
|
||||
| Item | Question | Status |
|
||||
|------|---------|--------|
|
||||
| **Chat Agent implementation** | Hermes as chat agent or separate Telegram bot? | Hermes (Model A/B hybrid) |
|
||||
| **PM Agent location** | Separate opencode session or Hermes mode? | Separate session (Model B) |
|
||||
| **Session timeout** | How long until inactive sessions are paused? | Pending |
|
||||
| **Message history** | Store in Hermes context or external database? | Pending |
|
||||
|
||||
### 7.3 Design Decisions Pending
|
||||
### 7.2 Design Decisions Pending
|
||||
|
||||
| Item | Question |
|
||||
|------|----------|
|
||||
@@ -414,5 +360,4 @@ When a Coding Agent starts, it:
|
||||
|
||||
## Status History
|
||||
|
||||
- 2026-03-30: Added Phase 3 architecture notes, updated status
|
||||
- 2026-03-27: Initial architecture draft
|
||||
- 2025-03-27: Initial architecture draft
|
||||
|
||||
@@ -1,170 +0,0 @@
|
||||
# Kugetsu Phase 3a Installation Guide
|
||||
|
||||
Guide for setting up the Kugetsu Chat Agent (Phase 3a) on a new host/container.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Hermes Agent** installed and configured
|
||||
2. **Telegram bot** created via @BotFather
|
||||
3. **kugetsu CLI** installed
|
||||
4. **opencode** installed
|
||||
|
||||
## Step 1: Verify Hermes Installation
|
||||
|
||||
```bash
|
||||
hermes version
|
||||
hermes config show # Check Telegram is configured
|
||||
```
|
||||
|
||||
## Step 2: Link Skills to Hermes
|
||||
|
||||
```bash
|
||||
# Create skill directories
|
||||
mkdir -p ~/.hermes/skills/kugetsu-chat
|
||||
|
||||
# Link skills from kugetsu repo (adjust path as needed)
|
||||
KUGEETSU_DIR="/path/to/kugetsu" # e.g., ~/repositories/kugetsu
|
||||
|
||||
ln -sf "$KUGEETSU_DIR/skills/kugetsu-chat" ~/.hermes/skills/kugetsu-chat
|
||||
```
|
||||
|
||||
## Step 3: Install Chat Agent SOUL
|
||||
|
||||
```bash
|
||||
# Copy SOUL.md to Hermes home (this defines the Chat Agent personality)
|
||||
cp "$KUGEETSU_DIR/skills/kugetsu-chat/SOUL.md" ~/.hermes/SOUL-chat.md
|
||||
```
|
||||
|
||||
## Step 4: Verify Gateway is Running
|
||||
|
||||
```bash
|
||||
hermes gateway status
|
||||
# If stopped:
|
||||
hermes gateway start
|
||||
```
|
||||
|
||||
## Step 5: Initialize kugetsu
|
||||
|
||||
**WARNING:** This requires an interactive terminal (TTY) because it spawns the opencode TUI.
|
||||
|
||||
You must run this in an **interactive shell**, not via `ssh remote "kugetsu init"`:
|
||||
|
||||
```bash
|
||||
# Option 1: SSH with TTY allocation
|
||||
ssh -t user@host "kugetsu init"
|
||||
|
||||
# Option 2: Connect to existing session and run
|
||||
ssh user@host
|
||||
kugetsu init # Run manually in the SSH session
|
||||
```
|
||||
|
||||
This creates:
|
||||
- **Base session** (for forking dev agents)
|
||||
- **PM Agent session** (persistent coordinator, loaded with kugetsu-pm context)
|
||||
|
||||
If you get `Error: init requires a terminal (TTY)`, you're running via non-interactive SSH. Use `-t` flag or connect directly.
|
||||
|
||||
## Step 6: Verify Setup
|
||||
|
||||
```bash
|
||||
# Check kugetsu status
|
||||
kugetsu status
|
||||
# Should output: ok
|
||||
|
||||
# List all sessions
|
||||
kugetsu list
|
||||
```
|
||||
|
||||
## Step 7: Test via Telegram
|
||||
|
||||
Start a conversation with your bot (@your_bot_username):
|
||||
|
||||
| Message | Expected |
|
||||
|---------|----------|
|
||||
| `hi` | Responds directly (small talk) |
|
||||
| `status?` | Routes to PM Agent |
|
||||
| `fix issue #5` | Routes to PM Agent |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### kugetsu command not found
|
||||
```bash
|
||||
export PATH="$HOME/.local/bin:$PATH"
|
||||
# Or add to ~/.bashrc
|
||||
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
|
||||
```
|
||||
|
||||
### Gateway not responding
|
||||
```bash
|
||||
hermes gateway restart
|
||||
```
|
||||
|
||||
### PM agent issues
|
||||
```bash
|
||||
# Diagnose
|
||||
kugetsu doctor
|
||||
|
||||
# Fix (if needed)
|
||||
kugetsu doctor --fix
|
||||
|
||||
# Or reinitialize
|
||||
kugetsu destroy --pm-agent -y
|
||||
kugetsu init
|
||||
```
|
||||
|
||||
## kugetsu Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `kugetsu init` | Initialize base + PM agent sessions |
|
||||
| `kugetsu status` | Check if kugetsu is ready |
|
||||
| `kugetsu delegate <msg>` | Send message to PM agent |
|
||||
| `kugetsu doctor [--fix]` | Diagnose and fix issues |
|
||||
| `kugetsu start <issue-ref> <msg>` | Start dev agent for issue |
|
||||
| `kugetsu continue <issue-ref> <msg>` | Continue existing issue session |
|
||||
| `kugetsu list` | List all tracked sessions |
|
||||
| `kugetsu prune [--force]` | Clean up orphaned sessions |
|
||||
|
||||
## File Locations
|
||||
|
||||
| File | Location | Purpose |
|
||||
|------|----------|---------|
|
||||
| Chat Agent SOUL | `~/.hermes/SOUL-chat.md` | Personality |
|
||||
| kugetsu-chat skill | `~/.hermes/skills/kugetsu-chat/` | Routing behavior |
|
||||
| kugetsu | `~/.local/bin/kugetsu` | Main CLI |
|
||||
|
||||
~/.kugetsu/
|
||||
├── sessions/
|
||||
│ ├── base.json # Base opencode session
|
||||
│ └── pm-agent.json # PM Agent opencode session
|
||||
├── index.json # Session registry
|
||||
└── pm-agent.md # PM context (optional, injected at init)
|
||||
|
||||
## Architecture Summary
|
||||
|
||||
```
|
||||
~/.hermes/
|
||||
├── SOUL-chat.md # Chat Agent personality
|
||||
└── skills/
|
||||
└── kugetsu-chat/ # Routing + delegation via kugetsu CLI
|
||||
|
||||
~/.kugetsu/
|
||||
├── sessions/
|
||||
│ ├── base.json # Base opencode session
|
||||
│ └── pm-agent.json # PM Agent opencode session
|
||||
├── index.json # Session registry
|
||||
└── pm-agent.md # PM context (optional)
|
||||
|
||||
~/.local/bin/
|
||||
└── kugetsu # Main CLI (handles delegation, status, doctor)
|
||||
```
|
||||
|
||||
## PM Context (Optional)
|
||||
|
||||
To customize PM Agent behavior, create `~/.kugetsu/pm-agent.md` with additional context. This file is injected into the PM Agent session at init time.
|
||||
|
||||
## Security Notes
|
||||
|
||||
- Never commit `~/.kugetsu/` or SOUL files to version control
|
||||
- Bot tokens should be in environment variables, not files
|
||||
- PM agent session IDs are internal - don't expose to users
|
||||
@@ -1,240 +0,0 @@
|
||||
# Kugetsu Chat Architecture (Phase 3)
|
||||
|
||||
**Status:** Phase 3a Implemented (Testing in Progress)
|
||||
**Related Issue:** #19
|
||||
|
||||
## Overview
|
||||
|
||||
Phase 3 adds Telegram chat interface for mobile/phone UX. Users can interact with their agent team via natural language from any device with Telegram.
|
||||
|
||||
## Architecture: Model B (Separate Agents)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ User (Phone) │
|
||||
│ Telegram App │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ Telegram Protocol
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Hermes (Chat Agent Gateway) │
|
||||
│ - Receives messages from Telegram │
|
||||
│ - Interprets natural language │
|
||||
│ - Routes to appropriate agent session │
|
||||
│ - Maintains conversation context │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────┴─────────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────────┐ ┌─────────────────────────────┐
|
||||
│ Chat Agent Session │ │ PM Agent Session │
|
||||
│ (opencode session) │ │ (opencode session) │
|
||||
│ │ │ │
|
||||
│ Session ID: chat-agent │ │ Session ID: pm-agent │
|
||||
│ │ │ │
|
||||
│ - Handles casual chat │ │ - Coordinates tasks │
|
||||
│ - Clears context on │◄────────┼─── PM questions to user │
|
||||
│ unrelated messages │ │ │
|
||||
│ - Short interactions │ │ - Delegates to Dev Agents │
|
||||
└─────────────────────────┘ │ - Long-running work │
|
||||
└─────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Dev Agent Sessions │
|
||||
│ (opencode sessions via kugetsu) │
|
||||
│ │
|
||||
│ Session IDs: │
|
||||
│ - issue-1-pr │
|
||||
│ - issue-2-research │
|
||||
│ - fix-issue-3 │
|
||||
│ - ... │
|
||||
│ │
|
||||
│ - Work autonomously │
|
||||
│ - Output to Gitea │
|
||||
│ - One issue per session │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Gitea │
|
||||
│ Issues, PRs, Comments │
|
||||
│ (Permanent audit trail) │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Session Types
|
||||
|
||||
| Session | kugetsu Session ID | Purpose | Lifespan |
|
||||
|---------|---------------------|---------|----------|
|
||||
| Chat Agent | `chat-agent` | User conversation (Hermes) | Persistent |
|
||||
| PM Agent | `pm-agent` | Task coordination | Persistent |
|
||||
| PM Agent (repo-specific) | `pm-agent-{repo-name}` | Extends base PM for specific repo | Optional scaling |
|
||||
| Dev Agent | `issue-{n}-{type}` | Issue work | Until issue resolved |
|
||||
|
||||
### PM Agent Hierarchy
|
||||
|
||||
- **Base PM**: `pm-agent` - Generic 1-way/1-door agent
|
||||
- **Repo-specific PM**: `pm-agent-{repo-name}` - Extends base PM for specific repo (optional scaling)
|
||||
|
||||
## Message Routing (Hybrid - Option 3)
|
||||
|
||||
### Routing Rules
|
||||
|
||||
| User Message | Route To | Response |
|
||||
|--------------|----------|----------|
|
||||
| Casual chat | Chat Agent | Direct response |
|
||||
| Task request | PM Agent | Task created or clarification needed |
|
||||
| Status query | PM Agent | Current status |
|
||||
| "PM, be silent" | PM Agent | Mode changed to silent |
|
||||
| "PM, notify me" | PM Agent | Mode changed to notify |
|
||||
| Clarification | PM → Chat → User | PM asks via Hermes |
|
||||
|
||||
### Example Flows
|
||||
|
||||
#### Flow 1: Simple Task Request
|
||||
|
||||
```
|
||||
User: "create a test file for issue #5"
|
||||
│
|
||||
▼
|
||||
Hermes (Chat Gateway)
|
||||
│ Routes to PM
|
||||
▼
|
||||
PM Agent
|
||||
│ Sees clear task
|
||||
│ Creates kugetsu session: kugetsu start github.com/user/repo#5 "create test"
|
||||
▼
|
||||
Dev Agent (issue-5-pr session)
|
||||
│ Does work
|
||||
│ Posts PR to Gitea
|
||||
▼
|
||||
PM Agent
|
||||
│ Task done
|
||||
│ Checks: PM mode = notify?
|
||||
▼
|
||||
Hermes (Chat Gateway)
|
||||
│ "Issue #5 is done! PR created."
|
||||
▼
|
||||
User (Telegram)
|
||||
```
|
||||
|
||||
#### Flow 2: Task with Clarification
|
||||
|
||||
```
|
||||
User: "improve the thing"
|
||||
│
|
||||
▼
|
||||
Hermes (Chat Gateway)
|
||||
│ Routes to PM
|
||||
▼
|
||||
PM Agent
|
||||
│ Unclear - what thing? which repo?
|
||||
│ PM sends clarification request
|
||||
▼
|
||||
Hermes (Chat Gateway)
|
||||
│ "Which project did you mean? github.com/user/project or git.example.com/team/core?"
|
||||
▼
|
||||
User (Telegram): "git.example.com/team/core"
|
||||
│
|
||||
▼
|
||||
Hermes (Chat Gateway)
|
||||
│ PM receives clarification
|
||||
│ PM proceeds with task
|
||||
▼
|
||||
...continues as Flow 1...
|
||||
```
|
||||
|
||||
#### Flow 3: Silent Mode
|
||||
|
||||
```
|
||||
User: "work on issue #7 silently"
|
||||
│
|
||||
▼
|
||||
Hermes (Chat Gateway)
|
||||
│ Routes to PM
|
||||
▼
|
||||
PM Agent
|
||||
│ Sets mode = silent
|
||||
│ "Okay, I will work silently. Check Gitea for progress."
|
||||
▼
|
||||
...PM works in background...
|
||||
│
|
||||
▼
|
||||
User checks Gitea directly
|
||||
│ Sees PR, comments, progress
|
||||
│
|
||||
User: "status"
|
||||
│
|
||||
▼
|
||||
Hermes → PM
|
||||
│ PM responds with status
|
||||
▼
|
||||
User
|
||||
```
|
||||
|
||||
## PM Agent Modes
|
||||
|
||||
| Mode | Behavior | Trigger |
|
||||
|------|----------|---------|
|
||||
| **Notify** (default) | PM sends completion message | `pm notify` or default |
|
||||
| **Silent** | PM works quietly | `pm silent` or `pm be quiet` |
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Hermes as Gateway
|
||||
|
||||
Hermes handles:
|
||||
- Telegram message reception
|
||||
- Natural language interpretation
|
||||
- Session routing
|
||||
- Response formatting
|
||||
|
||||
### opencode Sessions
|
||||
|
||||
Each agent runs in its own opencode session via kugetsu:
|
||||
- Sessions persist across interactions
|
||||
- kugetsu manages session lifecycle
|
||||
- Each session has isolated context
|
||||
|
||||
### Gitea Integration
|
||||
|
||||
All agent work outputs to Gitea:
|
||||
- Issue comments for progress
|
||||
- PRs for code changes
|
||||
- Permanent audit trail
|
||||
|
||||
### Context Management
|
||||
|
||||
#### Storage
|
||||
- **Primary**: Kugetsu session file (local JSON)
|
||||
- **Extension**: Gitea comments (fetched on-demand)
|
||||
|
||||
#### Fetch Triggers
|
||||
| Trigger | When |
|
||||
|---------|------|
|
||||
| **No context** | Initial load - PM fetches relevant issue/PR comments |
|
||||
| **Explicit request** | Agent decides to fetch more context |
|
||||
| **Insufficient** | Local context not helpful - like initial case |
|
||||
|
||||
#### Context Merge Strategy
|
||||
- **Default**: Append new context to existing
|
||||
- **Threshold**: Summarize + replace at 40% of model context window (dynamic based on model)
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **Telegram API vs Bot API**: Use long polling (Bot API) or MTProto (user session)?
|
||||
2. **Session timeout**: How long until inactive sessions are paused?
|
||||
3. **Message history**: Store in Hermes context or external database?
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Telegram Setup Guide](telegram-setup.md)
|
||||
- [kugetsu Architecture](kugetsu-architecture.md)
|
||||
- [Subagent Workflow](SUBAGENT_WORKFLOW.md)
|
||||
@@ -1,418 +0,0 @@
|
||||
# kugetsu Setup Guide
|
||||
|
||||
This guide covers setting up a server/container with kugetsu for remote agent interaction.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Prerequisites](#prerequisites)
|
||||
2. [Container Setup](#container-setup)
|
||||
3. [SSH Setup](#ssh-setup)
|
||||
4. [kugetsu Installation](#kugetsu-installation)
|
||||
5. [Usage](#usage)
|
||||
6. [Remote Access via SSH](#remote-access-via-ssh)
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Linux container (Incus, Docker, Podman, etc.)
|
||||
- systemd available inside container
|
||||
- SSH key for authentication (RSA, ED25519, or ECDSA)
|
||||
|
||||
---
|
||||
|
||||
## Container Setup
|
||||
|
||||
### Incus
|
||||
|
||||
```bash
|
||||
# Create container (Debian/Ubuntu)
|
||||
incus launch images:debian/12 <container-name>
|
||||
|
||||
# Or create Fedora container
|
||||
incus launch images:fedora/43 <container-name>
|
||||
|
||||
# Or use an existing container
|
||||
incus exec <container-name> -- bash
|
||||
|
||||
# Ensure systemd is installed
|
||||
# For Debian/Ubuntu:
|
||||
incus exec <container-name> -- apt-get update
|
||||
incus exec <container-name> -- apt-get install -y systemd
|
||||
|
||||
# For Fedora:
|
||||
incus exec <container-name> -- dnf install -y systemd
|
||||
|
||||
# Enable systemd in container (Incus specific - verify with your setup)
|
||||
incus config set <container-name> security.syscalls.intercept.systemd true
|
||||
|
||||
> **Note:** Container must be privileged or have CAP_SYS_ADMIN for systemd features.
|
||||
> The exact command may vary by Incus version - check Incus documentation for your setup.
|
||||
|
||||
---
|
||||
|
||||
## SSH Setup
|
||||
|
||||
### Automated Setup
|
||||
|
||||
Run the setup script inside your container:
|
||||
|
||||
```bash
|
||||
chmod +x skills/kugetsu/scripts/sshd-setup.sh
|
||||
bash skills/kugetsu/scripts/sshd-setup.sh <username>
|
||||
```
|
||||
|
||||
Replace `<username>` with your preferred username, or omit to use default `kugetsu`.
|
||||
|
||||
**The script automatically detects your OS and installs the correct packages.**
|
||||
|
||||
Supported OSes: Debian, Ubuntu, Fedora, RHEL, CentOS
|
||||
|
||||
### Manual Setup
|
||||
|
||||
If you prefer to set up SSH manually:
|
||||
|
||||
#### 1. Install openssh-server
|
||||
|
||||
**Debian/Ubuntu:**
|
||||
```bash
|
||||
apt-get update && apt-get install -y openssh-server sudo
|
||||
```
|
||||
|
||||
**Fedora/RHEL/CentOS:**
|
||||
```bash
|
||||
dnf install -y openssh-server sudo
|
||||
```
|
||||
|
||||
#### 2. Verify installation
|
||||
|
||||
```bash
|
||||
which sshd
|
||||
sshd -V
|
||||
```
|
||||
|
||||
#### 2. Create non-root user
|
||||
|
||||
```bash
|
||||
# Create user (e.g., 'agent')
|
||||
useradd -m -s /bin/bash agent
|
||||
|
||||
# Or use an existing user
|
||||
```
|
||||
|
||||
#### 3. Configure SSH
|
||||
|
||||
Edit `/etc/ssh/sshd_config`:
|
||||
|
||||
```
|
||||
PasswordAuthentication no
|
||||
PubkeyAuthentication yes
|
||||
PermitRootLogin no
|
||||
```
|
||||
|
||||
#### 4. Add SSH public key
|
||||
|
||||
```bash
|
||||
mkdir -p /home/<username>/.ssh
|
||||
chmod 700 /home/<username>/.ssh
|
||||
echo 'YOUR_PUBLIC_KEY' >> /home/<username>/.ssh/authorized_keys
|
||||
chmod 600 /home/<username>/.ssh/authorized_keys
|
||||
chown -R <username>:<username> /home/<username>/.ssh
|
||||
```
|
||||
|
||||
#### 5. Configure sudo for passwordless access
|
||||
|
||||
```bash
|
||||
echo '<username> ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/<username>
|
||||
chmod 0440 /etc/sudoers.d/<username>
|
||||
```
|
||||
|
||||
#### 6. Start sshd
|
||||
|
||||
```bash
|
||||
systemctl enable sshd
|
||||
systemctl start sshd
|
||||
```
|
||||
|
||||
### Host-Side Port Forwarding
|
||||
|
||||
To access SSH from outside the host, configure port forwarding:
|
||||
|
||||
#### Incus
|
||||
|
||||
```bash
|
||||
# On the HOST (not inside container)
|
||||
incus config device add <container-name> sshd proxy listen=tcp:0.0.0.0:2222 connect=tcp:127.0.0.1:22
|
||||
```
|
||||
|
||||
#### Firewall
|
||||
|
||||
```bash
|
||||
# Allow SSH on host
|
||||
ufw allow 2222/tcp
|
||||
|
||||
# Or using iptables
|
||||
iptables -A INPUT -p tcp --dport 2222 -j ACCEPT
|
||||
```
|
||||
|
||||
### Verify SSH Setup
|
||||
|
||||
```bash
|
||||
# Test connection from host to container
|
||||
ssh -p 2222 <username>@localhost
|
||||
|
||||
# Verify sudo access
|
||||
ssh -p 2222 <username>@localhost sudo systemctl status sshd
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## kugetsu Installation
|
||||
|
||||
### Automated Install
|
||||
|
||||
```bash
|
||||
# If you have cloned the repository
|
||||
bash skills/kugetsu/scripts/kugetsu-install.sh
|
||||
|
||||
# Reload shell or source bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
kugetsu provides session management for opencode.
|
||||
|
||||
### Initialize
|
||||
|
||||
```bash
|
||||
# Create base session (requires TTY)
|
||||
kugetsu init
|
||||
```
|
||||
|
||||
### Start Task
|
||||
|
||||
```bash
|
||||
# Start new session for an issue
|
||||
kugetsu start <issue-ref> <message>
|
||||
|
||||
# Example
|
||||
kugetsu start github.com/shoko/kugetsu#11 "Implement SSH setup"
|
||||
```
|
||||
|
||||
### Continue Task
|
||||
|
||||
```bash
|
||||
# Continue existing session
|
||||
kugetsu continue <issue-ref> [message]
|
||||
|
||||
# Resume with auto-filled last message
|
||||
kugetsu continue github.com/shoko/kugetsu#11
|
||||
```
|
||||
|
||||
### List Sessions
|
||||
|
||||
```bash
|
||||
# List interrupted sessions (default)
|
||||
kugetsu list
|
||||
|
||||
# List all sessions
|
||||
kugetsu list --all
|
||||
```
|
||||
|
||||
### Destroy Session
|
||||
|
||||
```bash
|
||||
# Destroy session for issue
|
||||
kugetsu destroy <issue-ref> [-y]
|
||||
|
||||
# Destroy base session
|
||||
kugetsu destroy --base [-y]
|
||||
```
|
||||
|
||||
### Help
|
||||
|
||||
```bash
|
||||
kugetsu help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Remote Access via SSH
|
||||
|
||||
Once SSH is configured, you can interact with kugetsu from anywhere:
|
||||
|
||||
### Basic SSH Access
|
||||
|
||||
```bash
|
||||
# Connect to container
|
||||
ssh -p 2222 <username>@<host-ip>
|
||||
|
||||
# Run kugetsu commands
|
||||
kugetsu list
|
||||
kugetsu start github.com/shoko/kugetsu#11 "Fix bug"
|
||||
```
|
||||
|
||||
### Spawn and Forget
|
||||
|
||||
For long-running tasks, SSH and spawn:
|
||||
|
||||
```bash
|
||||
ssh -p 2222 <username>@<host-ip> \
|
||||
"kugetsu start github.com/shoko/kugetsu#11 'Implement feature' && echo 'Task done' | tee /tmp/task.log"
|
||||
```
|
||||
|
||||
### Port Forwarding for Web UI
|
||||
|
||||
If opencode has a web UI:
|
||||
|
||||
```bash
|
||||
ssh -p 2222 -L 3000:localhost:3000 <username>@<host-ip>
|
||||
```
|
||||
|
||||
### SCP/File Transfer
|
||||
|
||||
```bash
|
||||
# Copy files from container
|
||||
scp -P 2222 <username>@<host-ip>:/path/in/container ./local-path
|
||||
|
||||
# Copy files to container
|
||||
scp -P 2222 ./local-file <username>@<host-ip>:/path/in/container
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Remote Access via Tailscale (Optional)
|
||||
|
||||
Tailscale provides VPN access without requiring a public IP on the host. Each container gets its own unique Tailscale IP and can be accessed from any device on your Tailscale network.
|
||||
|
||||
### Why Tailscale?
|
||||
|
||||
| | Port Forwarding | Tailscale |
|
||||
|--|-----------------|-----------|
|
||||
| Public IP required | Yes | No |
|
||||
| Firewall config | Needed | Not needed |
|
||||
| Cross-network access | Limited | Full |
|
||||
| Setup complexity | Higher | Lower |
|
||||
|
||||
### Automated Setup
|
||||
|
||||
Run the Tailscale setup script inside your container:
|
||||
|
||||
```bash
|
||||
chmod +x skills/kugetsu/scripts/tailscale-setup.sh
|
||||
bash skills/kugetsu/scripts/tailscale-setup.sh <username> <device-name>
|
||||
```
|
||||
|
||||
Arguments:
|
||||
- `<username>`: SSH user that will be created (defaults to current user)
|
||||
- `<device-name>`: Tailscale hostname (defaults to current hostname)
|
||||
|
||||
### Authentication Methods
|
||||
|
||||
The script will prompt you to choose:
|
||||
|
||||
**1. AUTHKEY (Recommended for automation)**
|
||||
- Pre-generate an auth key from: https://login.tailscale.com/admin/settings/keys
|
||||
- Click "Generate auth key", copy the key (starts with `tskey-auth-`)
|
||||
- Paste it when prompted
|
||||
|
||||
**2. Headless (Browser-based)**
|
||||
- Script will show a login URL
|
||||
- Open the URL in your browser and authenticate
|
||||
- Return to complete setup
|
||||
|
||||
### After Setup
|
||||
|
||||
1. Install Tailscale on your other devices: https://tailscale.com/download
|
||||
2. Log in with the same Tailscale account
|
||||
3. Connect via SSH using your device name:
|
||||
```bash
|
||||
ssh <username>@<device-name>
|
||||
```
|
||||
|
||||
Or use the Tailscale IP directly:
|
||||
```bash
|
||||
ssh <username>@<tailscale-ip>
|
||||
```
|
||||
|
||||
### Verify Connection
|
||||
|
||||
Inside the container:
|
||||
```bash
|
||||
tailscale status
|
||||
tailscale ip -4
|
||||
```
|
||||
|
||||
### Tailscale + SSH
|
||||
|
||||
Tailscale handles the network connection. Once connected via Tailscale, you can SSH normally and use kugetsu:
|
||||
|
||||
```bash
|
||||
ssh <username>@<device-name>
|
||||
kugetsu list
|
||||
kugetsu start github.com/shoko/kugetsu#11 "Fix bug"
|
||||
```
|
||||
|
||||
### Uninstall Tailscale
|
||||
|
||||
```bash
|
||||
sudo systemctl stop tailscaled
|
||||
sudo systemctl disable tailscaled
|
||||
sudo dnf remove tailscale # Fedora
|
||||
# or
|
||||
sudo apt remove tailscale # Debian/Ubuntu
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **Key-only authentication**: Password authentication is disabled
|
||||
- **Non-root user**: SSH user has limited privileges but can sudo
|
||||
- **Firewall**: Only port 2222 is exposed (not 22 on host)
|
||||
- **Container isolation**: Host filesystem is protected by container boundaries
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### SSH Connection Refused
|
||||
|
||||
```bash
|
||||
# Check sshd status inside container
|
||||
ssh -p 2222 <username>@<host-ip> sudo systemctl status sshd
|
||||
|
||||
# Restart sshd
|
||||
ssh -p 2222 <username>@<host-ip> sudo systemctl restart sshd
|
||||
```
|
||||
|
||||
### Permission Denied (Public Key)
|
||||
|
||||
```bash
|
||||
# Verify authorized_keys on container
|
||||
ssh -p 2222 <username>@<host-ip> cat ~/.ssh/authorized_keys
|
||||
|
||||
# Check key permissions
|
||||
ssh -p 2222 <username>@<host-ip> ls -la ~/.ssh/
|
||||
```
|
||||
|
||||
### kugetsu Command Not Found
|
||||
|
||||
```bash
|
||||
# Check PATH
|
||||
ssh -p 2222 <username>@<host-ip> 'echo $PATH'
|
||||
|
||||
# Re-run install (if repo is cloned on container)
|
||||
ssh -p 2222 <username>@<host-ip> 'bash ~/path/to/kugetsu/skills/kugetsu/scripts/kugetsu-install.sh'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [kugetsu Skill](../skills/kugetsu/SKILL.md) - Full kugetsu documentation
|
||||
- [kugetsu Architecture](kugetsu-architecture.md) - Technical details
|
||||
- [Subagent Workflow](SUBAGENT_WORKFLOW.md) - Multi-agent orchestration
|
||||
111
docs/kugetsu.md
111
docs/kugetsu.md
@@ -1,111 +0,0 @@
|
||||
# Kugetsu
|
||||
|
||||
**Status:** In Development
|
||||
|
||||
Kugetsu is an agent orchestration system that enables parallel task execution across multiple repositories through a hierarchical multi-agent architecture.
|
||||
|
||||
## Quick Overview
|
||||
|
||||
```
|
||||
Human (Executive)
|
||||
└── PM Agent (Task Coordinator)
|
||||
├── Dev Agent A → Issue 1 → PR
|
||||
├── Dev Agent B → Issue 2 → PR
|
||||
└── Dev Agent C → Issue 3 → PR
|
||||
```
|
||||
|
||||
Your focus shifts from doing to overseeing — reviewing PRs, approving plans, managing priorities.
|
||||
|
||||
## Core Components
|
||||
|
||||
| Component | Implementation | Purpose |
|
||||
|-----------|---------------|---------|
|
||||
| **Session Manager** | `kugetsu` CLI | Manages opencode sessions |
|
||||
| **Chat Interface** | Hermes + Telegram | Mobile UX (Phase 3) |
|
||||
| **PM Agent** | opencode session | Task coordination |
|
||||
| **Dev Agents** | opencode sessions | Execute tasks |
|
||||
| **Communication Hub** | Gitea | Issues, PRs, Comments |
|
||||
|
||||
## Session Architecture
|
||||
|
||||
| Session | kugetsu ID | Purpose |
|
||||
|---------|-------------|---------|
|
||||
| Base Session | `base` | Initial TUI session for forking |
|
||||
| PM Agent | `pm-agent` | Task coordination |
|
||||
| Repo PM | `pm-agent-{repo}` | Repo-specific PM (optional) |
|
||||
| Dev Agent | `issue-{n}` | Per-issue work |
|
||||
|
||||
## Current Capabilities
|
||||
|
||||
### Phase 1: Remote Access ✅
|
||||
- SSH access to container
|
||||
- Tailscale VPN for cross-network access
|
||||
- See [docs/kugetsu-setup.md](kugetsu-setup.md)
|
||||
|
||||
### Phase 2: API Interface 📋
|
||||
- Planned: REST/CLI API for task assignment
|
||||
- Status polling
|
||||
- Webhook support
|
||||
|
||||
### Phase 3: Chat Integration 📋
|
||||
- Telegram bot for mobile UX
|
||||
- Natural language interaction
|
||||
- See [docs/kugetsu-chat.md](kugetsu-chat.md)
|
||||
|
||||
### Phase 4: Web Dashboard 📋
|
||||
- Visual task board
|
||||
- Agent status monitoring
|
||||
- Read-only dashboards
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://git.example.com/shoko/kugetsu.git
|
||||
|
||||
# Install kugetsu
|
||||
bash kugetsu/skills/kugetsu/scripts/kugetsu-install.sh
|
||||
|
||||
# Setup SSH (optional)
|
||||
bash kugetsu/skills/kugetsu/scripts/sshd-setup.sh <username>
|
||||
|
||||
# Setup Tailscale (optional)
|
||||
bash kugetsu/skills/kugetsu/scripts/tailscale-setup.sh <username>
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Initialize base session (requires TTY)
|
||||
kugetsu init
|
||||
|
||||
# Start work on issue
|
||||
kugetsu start github.com/user/repo#14 "fix bug"
|
||||
|
||||
# Continue later
|
||||
kugetsu continue github.com/user/repo#14 "add tests"
|
||||
|
||||
# List sessions
|
||||
kugetsu list
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| [kugetsu-architecture.md](kugetsu-architecture.md) | Detailed architecture |
|
||||
| [kugetsu-chat.md](kugetsu-chat.md) | Phase 3 chat design |
|
||||
| [kugetsu-setup.md](kugetsu-setup.md) | Setup guides |
|
||||
| [telegram-setup.md](telegram-setup.md) | Telegram bot setup |
|
||||
| [SUBAGENT_WORKFLOW.md](SUBAGENT_WORKFLOW.md) | Subagent execution |
|
||||
|
||||
## Priority Model
|
||||
|
||||
| Priority | Type |
|
||||
|----------|------|
|
||||
| 1 | Security |
|
||||
| 2 | Bugs |
|
||||
| 3 | Features |
|
||||
| 4 | Research |
|
||||
|
||||
Within each type: Critical > High > Medium > Low
|
||||
@@ -1,247 +0,0 @@
|
||||
# OpenCode Session Internals
|
||||
|
||||
This document contains findings about how OpenCode manages sessions, based on direct database investigation. Use this when debugging session-related issues in kugetsu.
|
||||
|
||||
## Database Location
|
||||
|
||||
```bash
|
||||
opencode db path
|
||||
# Returns: ~/.local/share/opencode/opencode.db
|
||||
```
|
||||
|
||||
## Session Table Schema
|
||||
|
||||
```sql
|
||||
CREATE TABLE `session` (
|
||||
`id` text PRIMARY KEY,
|
||||
`project_id` text NOT NULL,
|
||||
`parent_id` text, -- Parent session ID (for forked sessions)
|
||||
`slug` text NOT NULL, -- Auto-generated adjective-animal name
|
||||
`directory` text NOT NULL, -- Working directory for session
|
||||
`title` text NOT NULL,
|
||||
`version` text NOT NULL,
|
||||
`share_url` text,
|
||||
`summary_additions` integer,
|
||||
`summary_deletions` integer,
|
||||
`summary_files` integer,
|
||||
`summary_diffs` text,
|
||||
`revert` text,
|
||||
`permission` text, -- JSON array of permission rules
|
||||
`time_created` integer NOT NULL, -- Unix timestamp in milliseconds
|
||||
`time_updated` integer NOT NULL,
|
||||
`time_compacting` integer,
|
||||
`time_archived` integer,
|
||||
`workspace_id` text
|
||||
);
|
||||
```
|
||||
|
||||
## Session ID Format
|
||||
|
||||
OpenCode session IDs follow the format: `ses_<base62_chars>`
|
||||
|
||||
Example: `ses_2b4eb7afbffezJwifgucdLRkt8`
|
||||
|
||||
The ID appears to be generated using a timestamp-based algorithm with random components. Analysis of 118+ sessions shows:
|
||||
|
||||
- **No duplicate IDs** - Each session gets a unique ID even with concurrent forks
|
||||
- **No sequential patterns** - IDs are not sequential even for sessions created milliseconds apart
|
||||
- **Contains timestamp** - The first numeric portion appears to encode creation time
|
||||
|
||||
## Querying Sessions
|
||||
|
||||
### List all sessions
|
||||
|
||||
```bash
|
||||
opencode session list
|
||||
```
|
||||
|
||||
### Query database directly (requires sqlite3 or python)
|
||||
|
||||
```python
|
||||
import sqlite3
|
||||
conn = sqlite3.connect('/home/shoko/.local/share/opencode/opencode.db')
|
||||
cursor = conn.cursor()
|
||||
|
||||
# Get all sessions
|
||||
cursor.execute('SELECT id, parent_id, slug, directory FROM session')
|
||||
|
||||
# Get forked sessions (sessions with a parent)
|
||||
cursor.execute('SELECT id, parent_id FROM session WHERE parent_id IS NOT NULL')
|
||||
|
||||
# Get sessions by directory
|
||||
cursor.execute("SELECT id, slug FROM session WHERE directory LIKE '%kugetsu%'")
|
||||
```
|
||||
|
||||
## Session Relationships
|
||||
|
||||
### Parent-Child Relationships
|
||||
|
||||
When you run `opencode run --fork --session <parent_id>`, OpenCode:
|
||||
|
||||
1. Creates a NEW session with a unique ID
|
||||
2. Sets the `parent_id` field to reference the parent session
|
||||
3. The child session inherits context from parent but has its own workspace
|
||||
|
||||
### Session Detection in Kugetsu
|
||||
|
||||
Kugetsu uses `opencode session list` to detect newly created sessions. The output format is:
|
||||
|
||||
```
|
||||
ses_abc123def456
|
||||
ses_xyz789...
|
||||
```
|
||||
|
||||
Kugetsu's `cmd_start` workflow:
|
||||
|
||||
1. **Before fork**: List all sessions, store in array
|
||||
2. **Fork**: Run `opencode run --fork --session <parent>`
|
||||
3. **After fork**: List sessions again
|
||||
4. **Detect new**: Compare before/after arrays, exclude known sessions (base, pm-agent)
|
||||
|
||||
```bash
|
||||
# Store before sessions in array
|
||||
declare -a before_sessions=()
|
||||
while IFS= read -r sess; do
|
||||
before_sessions+=("$sess")
|
||||
done < <(opencode session list 2>/dev/null | grep -oP '^ses_\w+')
|
||||
|
||||
# Fork happens here...
|
||||
|
||||
# Find sessions not in before array
|
||||
while IFS= read -r sess; do
|
||||
# Skip base and pm-agent sessions
|
||||
[ "$sess" = "$base_session_id"" ] && continue
|
||||
[ "$sess" = "$pm_agent_session_id" ] && continue
|
||||
|
||||
# Check if session existed before
|
||||
local existed_before=false
|
||||
for before_sess in "${before_sessions[@]}"; do
|
||||
if [ "$sess" = "$before_sess" ]; then
|
||||
existed_before=true
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "$existed_before" = false ]; then
|
||||
new_session_id="$sess"
|
||||
break
|
||||
fi
|
||||
done < <(opencode session list 2>/dev/null | grep -oP '^ses_\w+')
|
||||
```
|
||||
|
||||
## Session Directories
|
||||
|
||||
Each session has a `directory` field indicating its working directory:
|
||||
|
||||
| Directory | Purpose |
|
||||
|-----------|---------|
|
||||
| `/home/shoko` | Base session, PM agent |
|
||||
| `/home/shoko/repositories/kugetsu` | Project sessions |
|
||||
| `~/.kugetsu/worktrees/<issue-ref>` | Per-issue worktrees |
|
||||
|
||||
## Permissions
|
||||
|
||||
Sessions have a `permission` field containing a JSON array:
|
||||
|
||||
```json
|
||||
[
|
||||
{"permission": "question", "pattern": "*", "action": "deny"},
|
||||
{"permission": "plan_enter", "pattern": "*", "action": "deny"},
|
||||
{"permission": "plan_exit", "pattern": "*", "action": "deny"},
|
||||
{"permission": "external_directory", "pattern": "*", "action": "allow"}
|
||||
]
|
||||
```
|
||||
|
||||
### Common Permission Issues
|
||||
|
||||
**Issue**: `permission requested: external_directory (/path/*); auto-rejecting`
|
||||
|
||||
**Cause**: The session's `permission` field may be `NULL` or missing required rules.
|
||||
|
||||
**Fix**: Update via SQLite:
|
||||
|
||||
```python
|
||||
import sqlite3
|
||||
conn = sqlite3.connect('/home/shoko/.local/share/opencode/opencode.db')
|
||||
cursor = conn.cursor()
|
||||
|
||||
PERMISSION_JSON = '[{"permission":"question","pattern":"*","action":"deny"},{"permission":"plan_enter","pattern":"*","action":"deny"},{"permission":"plan_exit","pattern":"*","action":"deny"},{"permission":"external_directory","pattern":"*","action":"allow"}]'
|
||||
|
||||
cursor.execute("UPDATE session SET permission = ? WHERE id = ?",
|
||||
(PERMISSION_JSON, session_id))
|
||||
conn.commit()
|
||||
```
|
||||
|
||||
## Known Issues & Solutions
|
||||
|
||||
### Session ID Collision (Issue #81)
|
||||
|
||||
**Problem**: Forked sessions showing same ID as PM agent.
|
||||
|
||||
**Investigation Results**:
|
||||
- OpenCode does NOT generate duplicate IDs (verified with 118+ sessions)
|
||||
- Database shows unique IDs even for concurrent forks
|
||||
- Issue is in kugetsu's session detection logic, not opencode
|
||||
|
||||
**Solution**: Use array-based session detection (see above) instead of string/regex matching.
|
||||
|
||||
### Stale Permission NULL (Issue #36)
|
||||
|
||||
**Problem**: PM agent cannot access directories despite permissions.
|
||||
|
||||
**Root Cause**: Session created with `permission = NULL` in database.
|
||||
|
||||
**Detection**:
|
||||
```python
|
||||
cursor.execute("SELECT id FROM session WHERE permission IS NULL")
|
||||
```
|
||||
|
||||
**Fix**: Set permissions via kugetsu:
|
||||
```bash
|
||||
kugetsu doctor --fix-permissions
|
||||
```
|
||||
|
||||
## Useful Queries
|
||||
|
||||
### Find sessions by issue reference
|
||||
|
||||
```python
|
||||
# Find sessions for a specific issue worktree
|
||||
cursor.execute("SELECT id, slug FROM session WHERE directory LIKE '%issue-81%'")
|
||||
```
|
||||
|
||||
### Find orphaned sessions (no parent, old)
|
||||
|
||||
```python
|
||||
import time
|
||||
old_threshold = time.time() - (30 * 24 * 60 * 60) # 30 days ago
|
||||
|
||||
cursor.execute("""SELECT id, slug, directory, time_created
|
||||
FROM session
|
||||
WHERE parent_id IS NULL
|
||||
AND time_created < ?
|
||||
ORDER BY time_created""", (old_threshold * 1000,))
|
||||
```
|
||||
|
||||
### Count sessions per project
|
||||
|
||||
```python
|
||||
cursor.execute("""SELECT project_id, COUNT(*) as cnt
|
||||
FROM session
|
||||
GROUP BY project_id
|
||||
ORDER BY cnt DESC""")
|
||||
```
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
1. **Check current sessions**: `opencode session list`
|
||||
2. **Check database**: `opencode db "SELECT id, parent_id, slug FROM session ORDER BY time_created DESC LIMIT 10"`
|
||||
3. **Verify permissions**: Check if `permission` field is NULL or valid JSON
|
||||
4. **Check directory**: Ensure session directory exists and is accessible
|
||||
5. **Compare before/after**: When debugging detection, log both before and after session lists
|
||||
|
||||
## External References
|
||||
|
||||
- OpenCode Repository: https://github.com/opencode-ai/opencode
|
||||
- Session Management: Uses SQLite with unique constraint on `id` column
|
||||
- Fork Operation: Sets `parent_id` to establish relationship
|
||||
@@ -1,96 +0,0 @@
|
||||
# Telegram Bot Setup Guide
|
||||
|
||||
This guide covers creating and configuring a Telegram bot for kugetsu Phase 3 (Chat Integration).
|
||||
|
||||
## Create a Telegram Bot
|
||||
|
||||
### Step 1: Start BotFather
|
||||
|
||||
1. Open Telegram and search for **@BotFather**
|
||||
2. Click **Start** to begin
|
||||
|
||||
### Step 2: Create New Bot
|
||||
|
||||
Send the command:
|
||||
```
|
||||
/newbot
|
||||
```
|
||||
|
||||
BotFather will ask for:
|
||||
1. **Name** - A human-readable name (e.g., "Kugetsu Bot")
|
||||
2. **Username** - Must end in `bot` (e.g., `kugetsu_agent_bot`)
|
||||
|
||||
### Step 3: Save Your Token
|
||||
|
||||
BotFather will give you a token like:
|
||||
```
|
||||
1234567890:ABCdefGHIjklMNOpqrSTUvwxyz123456789
|
||||
```
|
||||
|
||||
**⚠️ Keep this token secret!** It allows access to your bot.
|
||||
|
||||
### Step 4: Set Bot Description (Optional)
|
||||
|
||||
```
|
||||
/setdescription
|
||||
```
|
||||
Enter a description like: "Kugetsu Chat Agent - Interact with your agent via Telegram"
|
||||
|
||||
### Step 5: Set Bot Picture (Optional)
|
||||
|
||||
```
|
||||
/setuserpic
|
||||
```
|
||||
Upload a profile picture for the bot.
|
||||
|
||||
---
|
||||
|
||||
## Configure Hermes for Telegram
|
||||
|
||||
*(This section will be expanded when Phase 3 implementation begins)*
|
||||
|
||||
### Required Environment Variables
|
||||
|
||||
```bash
|
||||
TELEGRAM_BOT_TOKEN="your-bot-token-here"
|
||||
TELEGRAM_API_ID="your-api-id" # From https://my.telegram.org
|
||||
TELEGRAM_API_HASH="your-api-hash" # From https://my.telegram.org
|
||||
```
|
||||
|
||||
### Hermes Configuration
|
||||
|
||||
```yaml
|
||||
# hermes/config.yaml
|
||||
telegram:
|
||||
enabled: true
|
||||
bot_token: ${TELEGRAM_BOT_TOKEN}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **Never commit bot tokens** to version control
|
||||
- Use environment variables or secrets management
|
||||
- Rotate tokens if compromised: `/revoke` in BotFather
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bot Not Responding
|
||||
|
||||
1. Check bot token is correct
|
||||
2. Verify Hermes is running and connected
|
||||
3. Check bot has not been blocked by user
|
||||
|
||||
### "Bot was blocked by the user"
|
||||
|
||||
The user has blocked your bot. They need to unblock it or start a new chat.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Phase 3: Chat Integration (Issue #19)](../issues/19)
|
||||
- [kugetsu Chat Architecture](kugetsu-chat.md)
|
||||
@@ -1,117 +0,0 @@
|
||||
---
|
||||
name: kugetsu-chat
|
||||
description: Kugetsu Chat Agent - REQUIRED skill for ALL non-casual Telegram messages. This skill MUST be loaded and used for task delegation.
|
||||
license: MIT
|
||||
compatibility: Requires Hermes agent with Telegram configured, kugetsu CLI, opencode sessions.
|
||||
metadata:
|
||||
author: shoko
|
||||
version: "4.0"
|
||||
---
|
||||
|
||||
# kugetsu-chat - REQUIRED SKILL FOR KUGETSU ROUTING
|
||||
|
||||
**THIS SKILL MUST BE USED for any message that is not casual conversation.**
|
||||
|
||||
## CRITICAL: When to Use This Skill
|
||||
|
||||
**YOU MUST LOAD AND USE THIS SKILL when:**
|
||||
- Any message containing "issue", "fix", "create", "test", "implement"
|
||||
- Any message containing issue numbers like "#5", "#14", "#123"
|
||||
- Any message that looks like a task request or status query
|
||||
- Any message containing "pm", "status", "progress", "work on"
|
||||
- Any message containing "notify", "updates", "notifications"
|
||||
|
||||
**DO NOT USE THIS SKILL for:**
|
||||
- "hi", "hello", "hey"
|
||||
- "thanks", "thank you"
|
||||
- "how are you", "what's up"
|
||||
- Casual greetings
|
||||
|
||||
## Required Actions
|
||||
|
||||
### Step 1: Load This Skill
|
||||
```
|
||||
/kugetsu-chat
|
||||
```
|
||||
|
||||
### Step 2: Check if kugetsu is initialized
|
||||
```
|
||||
terminal(command="kugetsu status", timeout=10)
|
||||
```
|
||||
|
||||
### Step 3: Route Based on Message Type
|
||||
|
||||
**For STATUS/UPDATE queries:**
|
||||
```
|
||||
terminal(command="kugetsu notify list", timeout=10)
|
||||
```
|
||||
Then include notifications in response.
|
||||
|
||||
**For TASK requests:**
|
||||
```
|
||||
terminal(command="kugetsu delegate '<entire user message>'", timeout=120)
|
||||
```
|
||||
|
||||
### Step 4: Relay the response to the user
|
||||
|
||||
## Delegation Command
|
||||
|
||||
The command for task delegation:
|
||||
|
||||
```bash
|
||||
kugetsu delegate '<user message>'
|
||||
```
|
||||
|
||||
Example:
|
||||
```
|
||||
terminal(command="kugetsu delegate 'fix issue #5 in github.com/shoko/kugetsu'", timeout=120)
|
||||
```
|
||||
|
||||
## Notification Checking
|
||||
|
||||
**When user asks about status/updates, check notifications:**
|
||||
|
||||
```bash
|
||||
kugetsu notify list
|
||||
```
|
||||
|
||||
Include any unread notifications in your response.
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Status Output | Meaning | Action |
|
||||
|--------------|---------|--------|
|
||||
| `ok` | kugetsu is ready | Proceed with delegation |
|
||||
| `kugetsu_not_initialized` | Not set up | Tell user to run `kugetsu init` |
|
||||
| `pm_agent_missing` | PM not created | Tell user to run `kugetsu init` |
|
||||
| `pm_agent_expired` | PM session expired | Tell user to run `kugetsu doctor --fix` |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**DELEGATION COMMAND:**
|
||||
```
|
||||
terminal(command="kugetsu delegate '<message>'", timeout=120)
|
||||
```
|
||||
|
||||
**CHECK NOTIFICATIONS:**
|
||||
```
|
||||
terminal(command="kugetsu notify list", timeout=10)
|
||||
```
|
||||
|
||||
**CHECK STATUS:**
|
||||
```
|
||||
terminal(command="kugetsu status", timeout=10)
|
||||
```
|
||||
|
||||
## Required Dependencies
|
||||
|
||||
- `kugetsu` CLI installed and in PATH
|
||||
- kugetsu initialized via `kugetsu init`
|
||||
|
||||
## Notes
|
||||
|
||||
- ALWAYS use `kugetsu delegate` command
|
||||
- ALWAYS wrap user message in single quotes inside the command
|
||||
- ALWAYS use timeout of at least 120 seconds for delegation
|
||||
- kugetsu delegates to the persistent PM agent session created during init
|
||||
- PM Agent writes task notifications to `~/.kugetsu/notifications.json`
|
||||
@@ -1,57 +0,0 @@
|
||||
# Kugetsu Chat Agent
|
||||
|
||||
You are the friendly, professional face of the Kugetsu agent team on Telegram.
|
||||
|
||||
## Your Voice
|
||||
|
||||
- **Friendly but professional** - Warm without being overly casual
|
||||
- **Concise** - Telegram users prefer short, punchy messages
|
||||
- **Helpful** - Guide users toward their goals without being pushy
|
||||
- **Patient** - Some users are new to multi-agent systems
|
||||
- **Direct** - Get to the point, no fluff
|
||||
|
||||
## CRITICAL: Routing Requirement
|
||||
|
||||
**YOU MUST ALWAYS use the kugetsu-chat skill for task delegation.**
|
||||
|
||||
For ANY message that is not casual conversation, you MUST:
|
||||
|
||||
1. First invoke: `/kugetsu-chat`
|
||||
2. Then use the delegation command from that skill
|
||||
|
||||
## Delegation Rules
|
||||
|
||||
| User Message Type | Example | Action |
|
||||
|------------------|---------|--------|
|
||||
| Casual | "hi", "hello", "thanks" | Respond directly |
|
||||
| Task | "fix issue #5", "create test for #14" | **MUST DELEGATE** |
|
||||
| Status | "status?", "what's on #7?" | **MUST DELEGATE** |
|
||||
| Mode | "pm notify", "pm silent" | **MUST DELEGATE** |
|
||||
| Question | "how does this work?" | May respond directly |
|
||||
|
||||
## Required Delegation Command
|
||||
|
||||
```
|
||||
terminal(command="kugetsu delegate '<user message>'", timeout=120)
|
||||
```
|
||||
|
||||
## When NOT to Delegate
|
||||
|
||||
Only for:
|
||||
- Greetings: "hi", "hello", "hey", "howdy"
|
||||
- Thanks: "thanks", "thank you", "thx"
|
||||
- Casual: "how are you", "what's up", "nice"
|
||||
- Simple questions about the bot itself
|
||||
|
||||
## Communication Style
|
||||
|
||||
- Keep messages short (Telegram prefers brevity)
|
||||
- Use emojis sparingly
|
||||
- Format code/terms in backticks
|
||||
- Be proactive with suggestions
|
||||
|
||||
## Security
|
||||
|
||||
- Never reveal session IDs or file paths
|
||||
- Keep responses user-friendly
|
||||
- If in doubt, ask for clarification
|
||||
@@ -1,194 +0,0 @@
|
||||
#!/bin/bash
|
||||
# kugetsu-chat setup script
|
||||
# Configures Hermes as Chat Agent for Phase 3a
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
KUGETSU_CHAT_DIR="$(dirname "$(dirname "$(readlink -f "$0")")")"
|
||||
HERMES_DIR="${HERMES_DIR:-$HOME/.hermes}"
|
||||
|
||||
usage() {
|
||||
cat << 'EOF'
|
||||
kugetsu-chat setup - Configure Hermes as Chat Agent
|
||||
|
||||
Usage:
|
||||
kugetsu-chat-setup.sh [--apply] [--check]
|
||||
|
||||
Options:
|
||||
--apply Apply the Chat Agent configuration to Hermes
|
||||
--check Verify configuration without applying
|
||||
|
||||
Examples:
|
||||
./kugetsu-chat-setup.sh --check # Check configuration
|
||||
./kugetsu-chat-setup.sh --apply # Apply configuration
|
||||
|
||||
EOF
|
||||
}
|
||||
|
||||
check_prerequisites() {
|
||||
echo "=== Checking Prerequisites ==="
|
||||
|
||||
if ! command -v hermes &> /dev/null; then
|
||||
echo "Error: Hermes is not installed or not in PATH"
|
||||
exit 1
|
||||
fi
|
||||
echo "✓ Hermes is installed"
|
||||
|
||||
if ! command -v kugetsu &> /dev/null; then
|
||||
echo "Error: kugetsu is not installed or not in PATH"
|
||||
exit 1
|
||||
fi
|
||||
echo "✓ kugetsu is installed"
|
||||
|
||||
if [ ! -f "$HERMES_DIR/config.yaml" ]; then
|
||||
echo "Error: Hermes config not found at $HERMES_DIR/config.yaml"
|
||||
exit 1
|
||||
fi
|
||||
echo "✓ Hermes config exists"
|
||||
|
||||
echo ""
|
||||
}
|
||||
|
||||
verify_kugetsu_init() {
|
||||
echo "=== Verifying kugetsu Initialization ==="
|
||||
|
||||
if [ ! -f "$HOME/.kugetsu/index.json" ]; then
|
||||
echo "Error: kugetsu not initialized. Run 'kugetsu init' first."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if ! grep -q '"pm_agent"' "$HOME/.kugetsu/index.json"; then
|
||||
echo "Error: kugetsu index.json missing pm_agent field"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
PM_AGENT=$(python3 -c "import json; print(json.load(open('$HOME/.kugetsu/index.json')).get('pm_agent', ''))" 2>/dev/null || echo "")
|
||||
if [ -z "$PM_AGENT" ] || [ "$PM_AGENT" = "null" ]; then
|
||||
echo "Error: PM agent session not initialized. Run 'kugetsu init' first."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✓ kugetsu is initialized with PM agent: $PM_AGENT"
|
||||
echo ""
|
||||
}
|
||||
|
||||
verify_telegram_config() {
|
||||
echo "=== Verifying Telegram Configuration ==="
|
||||
|
||||
if ! grep -q "TELEGRAM_HOME_CHANNEL" "$HERMES_DIR/config.yaml"; then
|
||||
echo "Warning: TELEGRAM_HOME_CHANNEL not found in Hermes config"
|
||||
echo " Telegram may not be configured. Run 'hermes gateway setup' to configure."
|
||||
else
|
||||
echo "✓ Telegram is configured in Hermes"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
}
|
||||
|
||||
install_soul() {
|
||||
echo "=== Installing Chat Agent SOUL ==="
|
||||
|
||||
SOUL_SOURCE="$KUGETSU_CHAT_DIR/SOUL.md"
|
||||
SOUL_TARGET="$HERMES_DIR/SOUL-chat.md"
|
||||
|
||||
if [ ! -f "$SOUL_SOURCE" ]; then
|
||||
echo "Error: SOUL.md not found at $SOUL_SOURCE"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
cp "$SOUL_SOURCE" "$SOUL_TARGET"
|
||||
echo "✓ Copied SOUL.md to $SOUL_TARGET"
|
||||
|
||||
echo ""
|
||||
}
|
||||
|
||||
install_skill() {
|
||||
echo "=== Installing kugetsu-chat Skill ==="
|
||||
|
||||
SKILL_SOURCE="$KUGETSU_CHAT_DIR"
|
||||
SKILL_TARGET="$HERMES_DIR/skills/kugetsu-chat"
|
||||
|
||||
if [ -L "$SKILL_TARGET" ]; then
|
||||
rm "$SKILL_TARGET"
|
||||
elif [ -d "$SKILL_TARGET" ]; then
|
||||
echo "Warning: $SKILL_TARGET already exists (not a symlink)"
|
||||
fi
|
||||
|
||||
ln -sf "$SKILL_SOURCE" "$SKILL_TARGET"
|
||||
echo "✓ Linked skill to $SKILL_TARGET"
|
||||
|
||||
echo ""
|
||||
}
|
||||
|
||||
apply_config() {
|
||||
echo "=== Applying Chat Agent Configuration ==="
|
||||
|
||||
check_prerequisites
|
||||
verify_kugetsu_init
|
||||
verify_telegram_config
|
||||
install_soul
|
||||
install_skill
|
||||
|
||||
echo "=== Configuration Complete ==="
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo "1. Run 'hermes gateway' to start the Telegram gateway"
|
||||
echo "2. Or run 'hermes' to use Chat Agent in CLI mode"
|
||||
echo ""
|
||||
echo "The Chat Agent will:"
|
||||
echo "- Receive Telegram messages"
|
||||
echo "- Handle small talk directly"
|
||||
echo "- Route task requests to PM Agent"
|
||||
echo "- Relay PM Agent responses back"
|
||||
}
|
||||
|
||||
check_config() {
|
||||
echo "=== Checking Chat Agent Configuration ==="
|
||||
echo ""
|
||||
|
||||
check_prerequisites
|
||||
verify_kugetsu_init
|
||||
verify_telegram_config
|
||||
|
||||
SOUL_TARGET="$HERMES_DIR/SOUL-chat.md"
|
||||
if [ -f "$SOUL_TARGET" ]; then
|
||||
echo "✓ Chat Agent SOUL is installed"
|
||||
else
|
||||
echo "○ Chat Agent SOUL not installed (run with --apply)"
|
||||
fi
|
||||
|
||||
SKILL_TARGET="$HERMES_DIR/skills/kugetsu-chat"
|
||||
if [ -L "$SKILL_TARGET" ]; then
|
||||
echo "✓ kugetsu-chat skill is linked"
|
||||
else
|
||||
echo "○ kugetsu-chat skill not linked (run with --apply)"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
}
|
||||
|
||||
main() {
|
||||
if [ $# -eq 0 ]; then
|
||||
usage
|
||||
exit 1
|
||||
fi
|
||||
|
||||
case "$1" in
|
||||
--apply)
|
||||
apply_config
|
||||
;;
|
||||
--check)
|
||||
check_config
|
||||
;;
|
||||
-h|--help)
|
||||
usage
|
||||
;;
|
||||
*)
|
||||
echo "Error: Unknown option '$1'"
|
||||
usage
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
main "$@"
|
||||
@@ -1,16 +1,16 @@
|
||||
---
|
||||
name: kugetsu
|
||||
description: Issue-driven session manager for opencode CLI. Manages base sessions and per-issue forked sessions with automatic indexing for headless orchestration.
|
||||
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, python3, and filesystem access.
|
||||
compatibility: Requires opencode CLI, bash, and filesystem access for session state.
|
||||
metadata:
|
||||
author: shoko
|
||||
version: "2.2"
|
||||
version: "1.1"
|
||||
---
|
||||
|
||||
# kugetsu - OpenCode Session Manager (Issue-Driven)
|
||||
# kugetsu - OpenCode Session Manager
|
||||
|
||||
Manages opencode sessions with a base session + forked session pattern optimized for headless orchestration. Each issue gets an isolated git worktree to prevent workspace conflicts.
|
||||
Manages opencode CLI sessions with state tracking and safe resume.
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -27,529 +27,122 @@ cp skills/kugetsu/scripts/kugetsu ~/.local/bin/kugetsu
|
||||
chmod +x ~/.local/bin/kugetsu
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
User overrides can be set in `~/.kugetsu/config`. This file is sourced on each kugetsu command call, so changes take effect immediately without re-initialization.
|
||||
|
||||
A default config file is created during `kugetsu init` with commented examples:
|
||||
|
||||
Or source directly when needed:
|
||||
```bash
|
||||
# User configuration overrides
|
||||
# Values set here take precedence over defaults
|
||||
# Changes take effect immediately (no re-init needed)
|
||||
|
||||
# Max concurrent dev agents (default: 3)
|
||||
# MAX_CONCURRENT_AGENTS=5
|
||||
. skills/kugetsu/scripts/kugetsu
|
||||
```
|
||||
|
||||
### Available Config Options
|
||||
## Session State
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `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` |
|
||||
| `QUEUE_DAEMON_INTERVAL_MINUTES` | 5 | How often daemon polls queue (in minutes) |
|
||||
| `QUEUE_CLEANUP_AGE_DAYS` | 7 | Auto-cleanup completed/error items older than N days |
|
||||
| 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 |
|
||||
|
||||
### Environment Variables for Agents
|
||||
## Session Directory
|
||||
|
||||
Agents receive environment variables through env files, not command-line injection. This allows agents to access credentials and tokens without manual injection on each command.
|
||||
|
||||
**Files created during `kugetsu init`:**
|
||||
- `~/.kugetsu/env/default.env` - Variables for all agents
|
||||
- `~/.kugetsu/env/pm-agent.env` - Variables for PM agent (overrides default)
|
||||
|
||||
**Commands:**
|
||||
```bash
|
||||
kugetsu env list # List all env files
|
||||
kugetsu env show [agent] # Show env file contents (values masked)
|
||||
kugetsu env set <key> <value> [agent] # Set a variable
|
||||
kugetsu env get <key> [agent] # Get a variable value
|
||||
kugetsu env rm <key> [agent] # Remove a variable
|
||||
```
|
||||
|
||||
**Example - Setting GITEA_TOKEN:**
|
||||
```bash
|
||||
# Set token for PM agent
|
||||
kugetsu env set GITEA_TOKEN ghp_xxx pm-agent
|
||||
|
||||
# Verify (token masked in output)
|
||||
kugetsu env show pm-agent
|
||||
|
||||
# Agent now has GITEA_TOKEN when delegated to
|
||||
```
|
||||
|
||||
**Sensitive values are automatically masked** in logs and display:
|
||||
- GITEA_TOKEN, GITHUB_TOKEN, GITLAB_TOKEN
|
||||
- API_KEY, PASSWORD, TOKEN, SECRET
|
||||
|
||||
**Usage in delegation:**
|
||||
```bash
|
||||
# PM agent will have GITEA_TOKEN from pm-agent.env
|
||||
kugetsu delegate "post comment on #69"
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Session Pattern
|
||||
- **Base Session**: Created once via TUI, used for forking dev agents
|
||||
- **PM Agent Session**: Created during init, persistent coordinator for task management
|
||||
- **Forked Sessions**: One per issue, branched from base via `opencode run --fork --session <base>`
|
||||
|
||||
### Git Worktree Isolation
|
||||
Each issue session gets its own git worktree to prevent conflicts:
|
||||
- Isolated working directory (no file collisions)
|
||||
- Isolated branch (no checkout conflicts)
|
||||
- Shared `.git` objects (efficient storage)
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
~/.kugetsu/
|
||||
├── sessions/
|
||||
│ ├── base.json # Base session metadata
|
||||
│ ├── pm-agent.json # PM agent session metadata
|
||||
│ └── github.com-shoko-kugetsu-14.json # Forked session per issue
|
||||
├── worktrees/
|
||||
│ ├── github.com-shoko-kugetsu-14/ # Isolated workdir for issue #14
|
||||
│ └── github.com-shoko-kugetsu-15/ # Isolated workdir for issue #15
|
||||
├── queue/
|
||||
│ ├── items/ # Queue item JSON files
|
||||
│ ├── daemon.pid # Daemon process ID
|
||||
│ └── daemon.log # Daemon log output
|
||||
└── index.json # Maps session IDs and issue refs to session files
|
||||
```
|
||||
|
||||
### Index File
|
||||
```json
|
||||
{
|
||||
"base": "ses_abc123",
|
||||
"pm_agent": "ses_pm_xyz789",
|
||||
"issues": {
|
||||
"github.com/shoko/kugetsu#14": "github.com-shoko-kugetsu-14.json"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Session File
|
||||
```json
|
||||
{
|
||||
"type": "forked",
|
||||
"issue_ref": "github.com/shoko/kugetsu#14",
|
||||
"opencode_session_id": "ses_xyz789",
|
||||
"worktree_path": "/home/user/.kugetsu/worktrees/github.com-shoko-kugetsu-14",
|
||||
"created_at": "2026-03-29T18:16:10+02:00",
|
||||
"state": "idle"
|
||||
}
|
||||
```
|
||||
|
||||
## Issue Ref Format
|
||||
|
||||
All issue references use the format: `instance/user/repo#identifier`
|
||||
|
||||
Examples:
|
||||
- `github.com/shoko/kugetsu#14` (issue number)
|
||||
- `github.com/shoko/kugetsu#-discuss` (discussion, no issue number yet)
|
||||
- `gitlab.com/username/project#42` (issue number)
|
||||
|
||||
## Worktree Behavior
|
||||
|
||||
### On `kugetsu start`
|
||||
1. Derives worktree path from issue ref: `~/.kugetsu/worktrees/{sanitized-ref}/`
|
||||
2. If worktree exists: removes and recreates (guaranteed clean state)
|
||||
3. If worktree doesn't exist: creates fresh
|
||||
4. Clones repo, creates branch `fix/issue-{id}`
|
||||
5. Runs opencode with `--workdir` pointing to worktree
|
||||
|
||||
### On `kugetsu destroy`
|
||||
1. Removes worktree via `git worktree remove`
|
||||
2. Deletes session file and index entry
|
||||
|
||||
### Repo Configuration
|
||||
If the repo URL cannot be derived from the issue ref, add to `~/.kugetsu/repos.json`:
|
||||
```json
|
||||
{
|
||||
"github.com/shoko kugetsu#14": "https://custom.repo.url/owner/repo.git"
|
||||
}
|
||||
```
|
||||
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 init [--force]
|
||||
|
||||
Initialize base + PM agent sessions via TUI:
|
||||
### kugetsu start `<session_id>` `<message>`
|
||||
Start a new session:
|
||||
```bash
|
||||
kugetsu init
|
||||
kugetsu start mytask "fix bug #1"
|
||||
```
|
||||
- Creates session directory
|
||||
- Sets state to `used`
|
||||
- Stores PID and message
|
||||
- Runs: `opencode run --session <session_id> <message>`
|
||||
|
||||
- Requires a terminal (TTY) to spawn the opencode TUI
|
||||
- Creates base session and PM agent session
|
||||
- Stores both session IDs in `index.json`
|
||||
- Subsequent runs error unless `--force` is used
|
||||
|
||||
### kugetsu start `<issue-ref>` `<message>` [--debug]
|
||||
|
||||
Start task for an issue by forking from base session:
|
||||
### kugetsu list [--all]
|
||||
List sessions:
|
||||
```bash
|
||||
kugetsu start github.com/shoko/kugetsu#14 "fix authentication bug"
|
||||
kugetsu start github.com/shoko/kugetsu#-discuss "research auth options"
|
||||
kugetsu list # Shows only `left` (resumable)
|
||||
kugetsu list --all # Shows all states
|
||||
```
|
||||
|
||||
- Creates isolated git worktree for the issue
|
||||
- Forks new session from base
|
||||
- Requires PM agent to exist (created by init)
|
||||
- Uses `opencode run --fork --session <base-session-id> "<message>" --workdir <worktree>`
|
||||
|
||||
### kugetsu continue `<issue-ref>` `<message>` [--debug]
|
||||
|
||||
Continue work on an existing issue session:
|
||||
### kugetsu resume `<session_id>` [message]
|
||||
Resume an interrupted session:
|
||||
```bash
|
||||
kugetsu continue github.com/shoko/kugetsu#14 "add unit tests"
|
||||
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
|
||||
|
||||
- Looks up session file from index
|
||||
- Uses `opencode run --continue --session <opencode-session-id> "<message>" --workdir <worktree>`
|
||||
|
||||
### kugetsu list
|
||||
|
||||
List all tracked sessions:
|
||||
### kugetsu stop `<session_id>`
|
||||
Stop a session gracefully:
|
||||
```bash
|
||||
kugetsu list
|
||||
kugetsu stop mytask
|
||||
```
|
||||
- Sends SIGTERM to process
|
||||
- Sets state to `idle`
|
||||
|
||||
Output:
|
||||
```
|
||||
ISSUE_REF TYPE SESSION_ID WORKTREE
|
||||
────────────────────────────────────────────────────────────────────────────────────────────────────────
|
||||
(base) base ses_abc123 N/A
|
||||
(pm-agent) pm_agent ses_pm_xyz789 N/A
|
||||
github.com/shoko/kugetsu#14 forked ses_xyz789 /home/user/.kugetsu/worktrees/github.com-shoko-kugetsu-14
|
||||
```
|
||||
|
||||
### kugetsu prune [--force]
|
||||
|
||||
Remove orphaned sessions and worktrees:
|
||||
### kugetsu destroy `<session_id>` [-y]
|
||||
Delete a session:
|
||||
```bash
|
||||
kugetsu prune # Shows what would be deleted
|
||||
kugetsu prune --force # Deletes orphaned items
|
||||
kugetsu destroy mytask # Prompts for confirmation (default: N)
|
||||
kugetsu destroy mytask -y # Skips confirmation
|
||||
```
|
||||
- Errors if session is `used` (use `stop` first)
|
||||
- Errors if session not found
|
||||
|
||||
- Orphaned = session files or worktrees not in index
|
||||
- Always keeps `base.json` and `pm-agent.json`
|
||||
- Useful after opencode session cleanup
|
||||
|
||||
### kugetsu destroy `<issue-ref>` [-y]
|
||||
|
||||
Delete session and worktree for specific issue:
|
||||
### kugetsu destroy --all [-y]
|
||||
Delete all sessions:
|
||||
```bash
|
||||
kugetsu destroy github.com/shoko/kugetsu#14 # Prompts for confirmation
|
||||
kugetsu destroy github.com/shoko/kugetsu#14 -y # Skips confirmation
|
||||
kugetsu destroy --all # Prompts for confirmation (default: N)
|
||||
kugetsu destroy --all -y # Skips confirmation
|
||||
```
|
||||
- Useful for fresh start
|
||||
|
||||
### kugetsu help
|
||||
Show usage help.
|
||||
|
||||
## State Transitions
|
||||
|
||||
```
|
||||
start ──────────────► used ──────► idle (stop/SIGTERM)
|
||||
│
|
||||
└──────► left (kill/SIGINT/crash)
|
||||
│
|
||||
▼
|
||||
destroy (delete)
|
||||
```
|
||||
|
||||
### kugetsu destroy --pm-agent [-y]
|
||||
## Example Workflow
|
||||
|
||||
Delete PM agent session (requires explicit `--pm-agent`):
|
||||
```bash
|
||||
kugetsu destroy --pm-agent -y
|
||||
```
|
||||
# Start a long-running task
|
||||
kugetsu start issue42 "implement feature X"
|
||||
|
||||
### kugetsu destroy --base [-y]
|
||||
# ... time passes, connection drops ...
|
||||
|
||||
Delete base session (requires explicit `--base`):
|
||||
```bash
|
||||
kugetsu destroy --base -y
|
||||
```
|
||||
|
||||
**Note**: Destroying base also destroys PM agent since PM depends on base.
|
||||
|
||||
### kugetsu delegate `<message>`
|
||||
|
||||
Send a message to the PM agent for task coordination via queue:
|
||||
```bash
|
||||
kugetsu delegate "work on issue #14"
|
||||
kugetsu delegate "review PR #92"
|
||||
```
|
||||
|
||||
- **Always enqueues** (fire-and-forget): returns immediately
|
||||
- Queue daemon polls queue and invokes PM when slots available
|
||||
- Tasks are processed FIFO (first-in-first-out)
|
||||
- Use `kugetsu queue list` to see pending tasks
|
||||
- Use `kugetsu queue-daemon logs` to debug queue processing
|
||||
|
||||
### 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 <list|add|remove|default|get>
|
||||
|
||||
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 <list|stats|clear>
|
||||
|
||||
Manage task queue for autonomous PM operation:
|
||||
```bash
|
||||
kugetsu queue list # Show queued tasks with status
|
||||
kugetsu queue stats # Show queue statistics (total, pending, notified, completed, error)
|
||||
kugetsu queue clear # Clean up old completed/error items
|
||||
kugetsu queue enqueue <issue-ref> <message> # Manually enqueue a task
|
||||
```
|
||||
|
||||
**Queue Item States:**
|
||||
- `pending` - Waiting in queue, daemon can pick up
|
||||
- `notified` - PM agent has picked up the task
|
||||
- `completed` - Dev agent finished, PR created
|
||||
- `error` - Timeout or failure
|
||||
|
||||
### kugetsu queue-daemon <start|stop|restart|status|logs>
|
||||
|
||||
Manage the queue daemon background process:
|
||||
```bash
|
||||
kugetsu queue-daemon start # Start daemon in background
|
||||
kugetsu queue-daemon stop # Stop daemon
|
||||
kugetsu queue-daemon restart # Restart daemon
|
||||
kugetsu queue-daemon status # Check if daemon is running
|
||||
kugetsu queue-daemon logs # Show recent daemon logs
|
||||
```
|
||||
|
||||
**Daemon Behavior:**
|
||||
1. Runs at configurable interval (default: 5 minutes)
|
||||
2. Checks queue for pending items
|
||||
3. For each pending item:
|
||||
- Acquires lock to prevent duplicate processing
|
||||
- Sources kugetsu-session.sh and calls `cmd_continue`
|
||||
- `cmd_continue` handles worktree/session creation and forks dev agent from base session
|
||||
- Updates queue item state to "notified"
|
||||
4. Uses per-issue locking to prevent race conditions
|
||||
5. Implements timeout for tasks that don't complete (marks as "error" after TASK_TIMEOUT_HOURS)
|
||||
|
||||
**Queue Directory:**
|
||||
```
|
||||
~/.kugetsu/queue/
|
||||
├── items/ # Queue item JSON files
|
||||
│ ├── q_1234567890.json # One file per queued task
|
||||
│ └── q_1234567891.json
|
||||
├── daemon.pid # Daemon process ID
|
||||
├── daemon.lock # Daemon lock file
|
||||
└── daemon.log # Daemon log output
|
||||
```
|
||||
|
||||
## Workflow Example
|
||||
|
||||
### First-time Setup
|
||||
```bash
|
||||
# Initialize kugetsu (requires TTY)
|
||||
kugetsu init
|
||||
|
||||
# Start the queue daemon (for autonomous operation)
|
||||
kugetsu queue-daemon start
|
||||
```
|
||||
|
||||
### Normal Workflow
|
||||
```bash
|
||||
# Enqueue tasks via delegate - agents will process them automatically
|
||||
kugetsu delegate "work on issue #14"
|
||||
kugetsu delegate "review PR #92"
|
||||
|
||||
# Check queue status
|
||||
kugetsu queue list # See pending tasks
|
||||
kugetsu queue stats # See statistics
|
||||
|
||||
# Debug queue daemon
|
||||
kugetsu queue-daemon status # Is daemon running?
|
||||
kugetsu queue-daemon logs # See daemon logs
|
||||
|
||||
# Continue work on existing issue
|
||||
kugetsu continue github.com/shoko/kugetsu#14 "add tests"
|
||||
|
||||
# List all sessions
|
||||
# Check what sessions are resumable
|
||||
kugetsu list
|
||||
|
||||
# Clean up orphaned items
|
||||
kugetsu prune --force
|
||||
# Resume with auto-filled message
|
||||
kugetsu resume issue42
|
||||
|
||||
# Delete session and worktree when done
|
||||
kugetsu destroy github.com/shoko/kugetsu#14
|
||||
# Later, when done
|
||||
kugetsu stop issue42
|
||||
|
||||
# When you want a fresh start
|
||||
kugetsu destroy --all
|
||||
```
|
||||
|
||||
### Queue Daemon Management
|
||||
```bash
|
||||
# Check if daemon is running
|
||||
kugetsu queue-daemon status
|
||||
|
||||
# View daemon logs for debugging
|
||||
kugetsu queue-daemon logs
|
||||
|
||||
# Restart daemon if needed
|
||||
kugetsu queue-daemon restart
|
||||
|
||||
# Stop daemon
|
||||
kugetsu queue-daemon stop
|
||||
```
|
||||
|
||||
## Headless Operation
|
||||
|
||||
This design solves the headless CLI limitation discovered in Issue #14:
|
||||
|
||||
1. **Problem**: `opencode run --session <new>` doesn't work headlessly (SSE stream terminates)
|
||||
2. **Solution**: Fork from existing base session, which works headlessly
|
||||
|
||||
The pattern:
|
||||
- Base session created once via TUI (interactive)
|
||||
- PM agent session created during init (persistent coordinator)
|
||||
- All subsequent work uses `--fork --session <base>` or `--continue --session <forked>`
|
||||
- Each session works in isolated git worktree
|
||||
|
||||
## Recovery
|
||||
|
||||
If opencode sessions become out of sync:
|
||||
|
||||
1. `kugetsu list` shows tracked sessions
|
||||
2. `kugetsu prune` removes orphaned files and worktrees
|
||||
3. For full reset: `kugetsu destroy --base -y && kugetsu init`
|
||||
|
||||
## Remote Access via SSH (Optional)
|
||||
|
||||
To access kugetsu from a remote machine, SSH setup is required.
|
||||
|
||||
### Automated Setup
|
||||
|
||||
Run the SSH setup script inside your container:
|
||||
|
||||
```bash
|
||||
chmod +x skills/kugetsu/scripts/sshd-setup.sh
|
||||
bash skills/kugetsu/scripts/sshd-setup.sh <username>
|
||||
```
|
||||
|
||||
Omit `<username>` to use default user `kugetsu`.
|
||||
|
||||
### What It Does
|
||||
|
||||
- Checks systemd prerequisite
|
||||
- Creates non-root user
|
||||
- Configures SSH for key-only authentication
|
||||
- Enables passwordless sudo for the user
|
||||
- Starts sshd via systemd
|
||||
|
||||
### After Setup
|
||||
|
||||
1. Add your SSH public key to `~/.ssh/authorized_keys` on the container
|
||||
2. Configure port forwarding on the host (see [docs/kugetsu-setup.md](../../docs/kugetsu-setup.md))
|
||||
3. Connect: `ssh -p 2222 <username>@<host-ip>`
|
||||
|
||||
### Remote Usage
|
||||
|
||||
Once connected via SSH, kugetsu works the same as local:
|
||||
|
||||
```bash
|
||||
kugetsu list
|
||||
kugetsu start github.com/shoko/kugetsu#14 "fix bug"
|
||||
kugetsu continue github.com/shoko/kugetsu#14
|
||||
```
|
||||
|
||||
### Documentation
|
||||
|
||||
See [docs/kugetsu-setup.md](../../docs/kugetsu-setup.md) for full remote access setup including host-side port forwarding and firewall configuration.
|
||||
|
||||
### Tailscale VPN (Alternative)
|
||||
|
||||
If your host does not have a public IP or you need access across different networks, Tailscale provides a VPN solution.
|
||||
|
||||
**Benefits:**
|
||||
- No public IP required
|
||||
- Each container gets its own unique Tailscale IP
|
||||
- Access from anywhere via Tailscale network
|
||||
- Normal internet access still works
|
||||
|
||||
**Setup:**
|
||||
|
||||
```bash
|
||||
chmod +x skills/kugetsu/scripts/tailscale-setup.sh
|
||||
bash skills/kugetsu/scripts/tailscale-setup.sh <username> <device-name>
|
||||
```
|
||||
|
||||
The script will:
|
||||
1. Install Tailscale (supports Debian/Ubuntu, Fedora)
|
||||
2. Start the tailscaled daemon
|
||||
3. Prompt for AUTHKEY or browser-based login
|
||||
4. Configure device name (defaults to current hostname)
|
||||
|
||||
**After Setup:**
|
||||
- From any Tailscale device: `ssh <username>@<device-name>`
|
||||
- Works across different networks without port forwarding
|
||||
|
||||
See [docs/kugetsu-setup.md](../../docs/kugetsu-setup.md) for full Tailscale setup documentation.
|
||||
|
||||
## Version History
|
||||
|
||||
### v0.2.3
|
||||
- **Queue daemon context drift fix** (issue #156): Daemon now sources kugetsu-session.sh and calls `cmd_continue` directly instead of forking PM session. This fixes context drift where daemon would lose track of task state.
|
||||
- **Daemon locking**: Added per-issue locking to prevent race conditions when multiple daemon instances run.
|
||||
- **Timeout handling**: Tasks that don't complete within TASK_TIMEOUT_HOURS are marked as "error".
|
||||
|
||||
## Without kugetsu
|
||||
|
||||
If kugetsu is not available, use opencode directly:
|
||||
If kugetsu is not installed, use opencode directly:
|
||||
```bash
|
||||
# Create base session (requires TTY)
|
||||
opencode
|
||||
# Note the session ID from: opencode session list
|
||||
|
||||
# Fork for issue
|
||||
opencode run --fork --session <base-session-id> "task"
|
||||
|
||||
# Continue
|
||||
opencode run --continue --session <forked-session-id> "continue"
|
||||
opencode run --session mytask "task description"
|
||||
opencode run --continue --session mytask "continue"
|
||||
opencode session list
|
||||
```
|
||||
|
||||
Tradeoff: No issue mapping, no index, manual session tracking, no worktree isolation.
|
||||
Tradeoff: No state tracking, no auto-fill, no filtered list, no confirmation prompts.
|
||||
|
||||
@@ -1,165 +0,0 @@
|
||||
You are a PM (Project Manager) for software development.
|
||||
|
||||
Your role is COORDINATOR. You break down requests, delegate work, monitor progress, and report results. You NEVER write code. Not even small fixes. Not even one-liners. Not even documentation. If asked to write code: delegate it using `kugetsu start`.
|
||||
|
||||
## Response Modes
|
||||
|
||||
You have TWO response modes. Choose based on the user's request:
|
||||
|
||||
### Mode 1: Task Mode (Delegate)
|
||||
When the user asks for something that requires coding, implementation, or file changes:
|
||||
- "work on issue #81"
|
||||
- "close PR #42"
|
||||
- "create a PR for issue #91"
|
||||
- "fix the bug in login.js"
|
||||
- "add tests for the API"
|
||||
- Any request that modifies code or creates commits
|
||||
|
||||
**Action:** Delegate using `kugetsu start` or `kugetsu continue`.
|
||||
|
||||
### Mode 2: Conversation Mode (Answer Directly)
|
||||
When the user asks a question that doesn't require code changes:
|
||||
- "show open issues"
|
||||
- "what is the current state of repo"
|
||||
- "hi"
|
||||
- "show me recent commits"
|
||||
- "what issues are being worked on"
|
||||
- "what branches exist"
|
||||
- Any informational query
|
||||
|
||||
**Action:** Answer directly from available context or API calls.
|
||||
|
||||
## Write Permissions: Strict Boundary
|
||||
|
||||
PM has EXPLICIT write boundaries. You can ONLY write to two specific locations.
|
||||
|
||||
### PM can ONLY write to:
|
||||
- `~/.kugetsu/queue.json` - Queue state
|
||||
- `~/.kugetsu/logs/*` - Your logs
|
||||
|
||||
### PM can NEVER write to (read-only):
|
||||
- `~/.kugetsu/` - Everything else in this directory is read-only
|
||||
- `repositories/*` - All repository code
|
||||
- `skills/*` - All skill files, including PM skill files
|
||||
- **ANY directory outside `~/.kugetsu/`**
|
||||
- Any `.md` files, config files, scripts, or code
|
||||
|
||||
### If Asked to Write Outside ~/.kugetsu/:
|
||||
You MUST delegate to a dev agent using Task Mode.
|
||||
|
||||
## Tools for Delegation
|
||||
|
||||
### kugetsu start
|
||||
Create a NEW dev agent session for an issue that has no existing session/worktree.
|
||||
|
||||
```
|
||||
kugetsu start <issue-ref> <task description>
|
||||
```
|
||||
|
||||
**Params:**
|
||||
- `issue-ref`: Format `instance/user/repo#number`
|
||||
- Example: `github.com/shoko/kugetsu#81`
|
||||
- Example: `git.fbrns.co/shoko/kugetsu#118`
|
||||
- `task description`: What the agent should do (be specific)
|
||||
|
||||
**Returns:** Creates new worktree and dev session, returns session ID
|
||||
|
||||
**When to use:** When there is NO existing session or worktree for this issue.
|
||||
|
||||
---
|
||||
|
||||
### kugetsu continue
|
||||
Continue an EXISTING dev agent session that already has a worktree/session.
|
||||
|
||||
```
|
||||
kugetsu continue <issue-ref> [additional instructions]
|
||||
```
|
||||
|
||||
**Params:**
|
||||
- `issue-ref`: Format `instance/user/repo#number`
|
||||
- `additional instructions`: (optional) Extra context or changed instructions
|
||||
|
||||
**Returns:** Continues existing session, returns session ID
|
||||
|
||||
**When to use:** When a worktree/session already exists for this issue (check with `kugetsu list`).
|
||||
|
||||
---
|
||||
|
||||
### How to Choose: start vs continue
|
||||
|
||||
| Scenario | Tool |
|
||||
|----------|------|
|
||||
| First time working on issue | `kugetsu start` |
|
||||
| Issue already has worktree/session | `kugetsu continue` |
|
||||
| Session exists but needs new task | `kugetsu continue <issue-ref> <new task>` |
|
||||
| Not sure if session exists | Check `kugetsu list` first, or use `kugetsu continue` (it will error if no session) |
|
||||
|
||||
**NOT `kugetsu delegate`** - that routes back to the PM (you). Use `kugetsu start` or `kugetsu continue` to create a NEW dev agent.
|
||||
|
||||
## Your Identity
|
||||
|
||||
You are the PM. Your job is to coordinate, not to code.
|
||||
|
||||
- You delegate ALL implementation tasks to dev agents using Task Mode
|
||||
- You answer informational queries directly in Conversation Mode
|
||||
- You review PRs but do not edit code yourself
|
||||
- You break down complex requests into delegate-able tasks
|
||||
- You monitor progress and keep stakeholders informed
|
||||
|
||||
## Delegation is Your Default Behavior for Tasks
|
||||
|
||||
When a request comes in:
|
||||
|
||||
1. **Identify Mode** - Is this a task (code change needed) or a conversation (info request)?
|
||||
2. **For Tasks:**
|
||||
- **Understand** - What needs to be built? What's the repo and issue?
|
||||
- **Choose Tool** - Use `kugetsu start` (new) or `kugetsu continue` (existing)?
|
||||
- **Delegate** - Call the appropriate tool with issue-ref and task
|
||||
- **Monitor** - Watch for PR creation and review
|
||||
- **Report** - Post final results to the issue
|
||||
3. **For Conversations:**
|
||||
- Answer directly using available context
|
||||
|
||||
## Few-Shot Examples
|
||||
|
||||
**User:** "Fix the bug in login.js"
|
||||
**Mode:** Task
|
||||
**You:** `kugetsu start <domain>/<user>/<repo>#123 Investigate and fix the login bug in login.js`
|
||||
|
||||
**User:** "Add tests for the API"
|
||||
**Mode:** Task
|
||||
**You:** `kugetsu start <domain>/<user>/<repo>#124 Write tests for the API module`
|
||||
|
||||
**User:** "Can you write a quick script to parse this JSON?"
|
||||
**Mode:** Task
|
||||
**You:** `kugetsu start <domain>/<user>/<repo>#125 Create a script to parse the JSON file`
|
||||
|
||||
**User:** "Update the README with installation instructions"
|
||||
**Mode:** Task
|
||||
**You:** `kugetsu start <domain>/<user>/<repo>#126 Update README with installation instructions`
|
||||
|
||||
**User:** "Create a file at /tmp/test.txt"
|
||||
**Mode:** Task
|
||||
**You:** `kugetsu start <domain>/<user>/<repo>#127 Create a file at /tmp/test.txt`
|
||||
|
||||
**User:** "What open issues do we have?"
|
||||
**Mode:** Conversation
|
||||
**You:** (Answer directly about open issues from the repository)
|
||||
|
||||
**User:** "Show me recent commits"
|
||||
**Mode:** Conversation
|
||||
**You:** (Answer directly about recent commits)
|
||||
|
||||
**User:** "Hi, how are you?"
|
||||
**Mode:** Conversation
|
||||
**You:** (Answer greeting directly)
|
||||
|
||||
---
|
||||
|
||||
## You Are the PM. You Coordinate. You Do Not Write Code.
|
||||
|
||||
This is not just a rule - it is your identity. The code you coordinate is built by others. Your value is in coordination, not coding.
|
||||
|
||||
---
|
||||
|
||||
*PM Agent v5 - Coordinators coordinate. Delegation is for tasks, conversation is for questions. Strict write boundary: ONLY ~/.kugetsu/.*
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,114 +0,0 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
KUGETSU_DIR="${KUGETSU_DIR:-$HOME/.kugetsu}"
|
||||
SESSIONS_DIR="$KUGETSU_DIR/sessions"
|
||||
WORKTREES_DIR="$KUGETSU_DIR/worktrees"
|
||||
REPOS_CONFIG="$KUGETSU_DIR/repos.json"
|
||||
INDEX_FILE="$KUGETSU_DIR/index.json"
|
||||
NOTIFICATIONS_FILE="$KUGETSU_DIR/notifications.json"
|
||||
LOGS_DIR="$KUGETSU_DIR/logs"
|
||||
ENV_DIR="${ENV_DIR:-$KUGETSU_DIR/env}"
|
||||
VERBOSITY_DIR="$KUGETSU_DIR/verbosity"
|
||||
|
||||
MAX_CONCURRENT_AGENTS="${MAX_CONCURRENT_AGENTS:-3}"
|
||||
KUGETSU_VERBOSITY="${KUGETSU_VERBOSITY:-default}"
|
||||
CONTEXT_DIR="${CONTEXT_DIR:-$KUGETSU_DIR/context}"
|
||||
ENABLE_CONTEXT_DUMP="${ENABLE_CONTEXT_DUMP:-true}"
|
||||
WORKTREE_CHECK_PR_STATUS="${WORKTREE_CHECK_PR_STATUS:-true}"
|
||||
|
||||
QUEUE_DIR="${QUEUE_DIR:-$KUGETSU_DIR/queue}"
|
||||
QUEUE_ITEMS_DIR="${QUEUE_ITEMS_DIR:-$QUEUE_DIR/items}"
|
||||
QUEUE_DAEMON_PID_FILE="${QUEUE_DAEMON_PID_FILE:-$QUEUE_DIR/daemon.pid}"
|
||||
QUEUE_DAEMON_LOCK_FILE="${QUEUE_DAEMON_LOCK_FILE:-$QUEUE_DIR/daemon.lock}"
|
||||
QUEUE_DAEMON_LOG_FILE="${QUEUE_DAEMON_LOG_FILE:-$QUEUE_DIR/daemon.log}"
|
||||
QUEUE_DAEMON_INTERVAL_MINUTES="${QUEUE_DAEMON_INTERVAL_MINUTES:-5}"
|
||||
QUEUE_CLEANUP_AGE_DAYS="${QUEUE_CLEANUP_AGE_DAYS:-7}"
|
||||
TASK_TIMEOUT_HOURS="${TASK_TIMEOUT_HOURS:-1}"
|
||||
|
||||
NETWORK_RETRY_ATTEMPTS="${NETWORK_RETRY_ATTEMPTS:-3}"
|
||||
NETWORK_RETRY_DELAY_SECONDS="${NETWORK_RETRY_DELAY_SECONDS:-5}"
|
||||
KUGETSU_BASE_BRANCH="${KUGETSU_BASE_BRANCH:-origin/main}"
|
||||
|
||||
# Load user config overrides (~/.kugetsu/config)
|
||||
if [ -f "$KUGETSU_DIR/config" ]; then
|
||||
source "$KUGETSU_DIR/config"
|
||||
fi
|
||||
|
||||
mask_sensitive_vars() {
|
||||
local line="${1:-}"
|
||||
for var in GITEA_TOKEN GITHUB_TOKEN GITLAB_TOKEN API_KEY PASSWORD TOKEN SECRET; do
|
||||
if [[ "$line" =~ $var ]]; then
|
||||
line=$(echo "$line" | sed -E "s/=.*/=***MASKED***/")
|
||||
fi
|
||||
done
|
||||
echo "$line"
|
||||
}
|
||||
|
||||
strip_ansi_codes() {
|
||||
local line="${1:-}"
|
||||
echo "$line" | sed 's/\x1b\[[0-9;]*m//g' | sed 's/\x1b\[[0-9;]*[a-zA-Z]//g'
|
||||
}
|
||||
|
||||
load_agent_env() {
|
||||
local agent_type="${1:-base}"
|
||||
local env_file="$ENV_DIR/${agent_type}.env"
|
||||
|
||||
if [ -f "$env_file" ]; then
|
||||
set -a
|
||||
source "$env_file"
|
||||
set +a
|
||||
elif [ -f "$ENV_DIR/default.env" ]; then
|
||||
set -a
|
||||
source "$ENV_DIR/default.env"
|
||||
set +a
|
||||
elif [ -f "$ENV_DIR/pm-agent.env" ]; then
|
||||
set -a
|
||||
source "$ENV_DIR/pm-agent.env"
|
||||
set +a
|
||||
fi
|
||||
}
|
||||
|
||||
set_debug_mode() {
|
||||
local filtered_args=()
|
||||
local debug_mode=false
|
||||
|
||||
for arg in "$@"; do
|
||||
case "$arg" in
|
||||
--debug)
|
||||
debug_mode=true
|
||||
;;
|
||||
*)
|
||||
filtered_args+=("$arg")
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
if [ "$debug_mode" = true ]; then
|
||||
export KUGETSU_VERBOSITY="debug"
|
||||
echo "[DEBUG] Debug mode enabled" >&2
|
||||
fi
|
||||
|
||||
echo "${filtered_args[@]}"
|
||||
}
|
||||
|
||||
retry_with_backoff() {
|
||||
local max_attempts="${1:-$NETWORK_RETRY_ATTEMPTS}"
|
||||
local delay_seconds="${2:-$NETWORK_RETRY_DELAY_SECONDS}"
|
||||
local command="$3"
|
||||
local remaining_attempts=$max_attempts
|
||||
|
||||
while [ $remaining_attempts -gt 0 ]; do
|
||||
if eval "$command"; then
|
||||
return 0
|
||||
fi
|
||||
remaining_attempts=$((remaining_attempts - 1))
|
||||
if [ $remaining_attempts -gt 0 ]; then
|
||||
log "warn" "retry_with_backoff" "Command failed, $remaining_attempts retries remaining. Waiting ${delay_seconds}s..."
|
||||
sleep "$delay_seconds"
|
||||
delay_seconds=$((delay_seconds * 2))
|
||||
fi
|
||||
done
|
||||
log "error" "retry_with_backoff" "Command failed after $max_attempts attempts"
|
||||
return 1
|
||||
}
|
||||
@@ -1,353 +0,0 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
read_index() {
|
||||
if [ -f "$INDEX_FILE" ]; then
|
||||
cat "$INDEX_FILE"
|
||||
else
|
||||
echo '{"base": null, "pm_agent": null, "issues": {}}'
|
||||
fi
|
||||
}
|
||||
|
||||
write_index() {
|
||||
local base="$1"
|
||||
local pm_agent="$2"
|
||||
local issues_json="$3"
|
||||
local temp_file="$INDEX_FILE.tmp.$$"
|
||||
printf '{"base": %s, "pm_agent": %s, "issues": %s}\n' "$base" "$pm_agent" "$issues_json" > "$temp_file"
|
||||
|
||||
if ! python3 -c "import json; json.load(open('$temp_file'))" 2>/dev/null; then
|
||||
echo "Error: write_index would create malformed JSON, aborting. base=$base, pm_agent=$pm_agent, issues_json=$issues_json" >&2
|
||||
rm -f "$temp_file"
|
||||
return 1
|
||||
fi
|
||||
|
||||
mv "$temp_file" "$INDEX_FILE"
|
||||
}
|
||||
|
||||
get_base_session_id() {
|
||||
local index=$(read_index)
|
||||
echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('base') or '')"
|
||||
}
|
||||
|
||||
get_pm_agent_session_id() {
|
||||
local index=$(read_index)
|
||||
echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('pm_agent') or '')"
|
||||
}
|
||||
|
||||
get_session_for_issue() {
|
||||
local issue_ref="$1"
|
||||
local index=$(read_index)
|
||||
echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('issues', {}).get('$issue_ref') or 'null')"
|
||||
}
|
||||
|
||||
set_base_in_index() {
|
||||
local session_id="$1"
|
||||
local index=$(read_index)
|
||||
local pm_agent=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('pm_agent') or 'null')")
|
||||
local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('issues', {})))")
|
||||
|
||||
if [ "$session_id" = "null" ]; then
|
||||
write_index "null" "$pm_agent" "$issues"
|
||||
else
|
||||
if [ "$pm_agent" = "null" ]; then
|
||||
write_index "\"$session_id\"" "null" "$issues"
|
||||
else
|
||||
write_index "\"$session_id\"" "\"$pm_agent\"" "$issues"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
set_pm_agent_in_index() {
|
||||
local session_id="$1"
|
||||
local index=$(read_index)
|
||||
local base=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('base') or 'null')")
|
||||
local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('issues', {})))")
|
||||
|
||||
if [ "$session_id" = "null" ]; then
|
||||
write_index "$base" "null" "$issues"
|
||||
else
|
||||
if [ "$base" = "null" ]; then
|
||||
write_index "null" "\"$session_id\"" "$issues"
|
||||
else
|
||||
write_index "\"$base\"" "\"$session_id\"" "$issues"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
add_issue_to_index() {
|
||||
local issue_ref="$1"
|
||||
local session_file="$2"
|
||||
|
||||
local index=$(read_index)
|
||||
local base=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('base') or 'null')")
|
||||
local pm_agent=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('pm_agent') or 'null')")
|
||||
|
||||
local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('issues', {})))")
|
||||
|
||||
issues=$(python3 -c "import sys, json; d=json.load(sys.stdin); d['$issue_ref']='$session_file'; print(json.dumps(d))" <<< "$issues")
|
||||
|
||||
if [ "$base" = "null" ]; then
|
||||
if [ "$pm_agent" = "null" ]; then
|
||||
write_index "null" "null" "$issues"
|
||||
else
|
||||
write_index "null" "\"$pm_agent\"" "$issues"
|
||||
fi
|
||||
else
|
||||
if [ "$pm_agent" = "null" ]; then
|
||||
write_index "\"$base\"" "null" "$issues"
|
||||
else
|
||||
write_index "\"$base\"" "\"$pm_agent\"" "$issues"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
remove_issue_from_index() {
|
||||
local issue_ref="$1"
|
||||
|
||||
local index=$(read_index)
|
||||
local base=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('base') or 'null')")
|
||||
local pm_agent=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(d.get('pm_agent') or 'null')")
|
||||
|
||||
local issues=$(echo "$index" | python3 -c "import sys, json; d=json.load(sys.stdin); print(json.dumps(d.get('issues', {})))")
|
||||
|
||||
issues=$(python3 -c "import sys, json; d=json.load(sys.stdin); d.pop('$issue_ref', None); print(json.dumps(d))" <<< "$issues")
|
||||
|
||||
if [ "$base" = "null" ]; then
|
||||
if [ "$pm_agent" = "null" ]; then
|
||||
write_index "null" "null" "$issues"
|
||||
else
|
||||
write_index "null" "\"$pm_agent\"" "$issues"
|
||||
fi
|
||||
else
|
||||
if [ "$pm_agent" = "null" ]; then
|
||||
write_index "\"$base\"" "null" "$issues"
|
||||
else
|
||||
write_index "\"$base\"" "\"$pm_agent\"" "$issues"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
validate_issue_ref() {
|
||||
local issue_ref="$1"
|
||||
|
||||
if [[ ! "$issue_ref" =~ ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+#[0-9]+$ ]]; then
|
||||
echo "Error: Invalid issue ref format: '$issue_ref'" >&2
|
||||
echo "Expected format: instance/user/repo#number" >&2
|
||||
echo "Example: github.com/shoko/kugetsu#14" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
read_json_file() {
|
||||
local file_path="$1"
|
||||
if [ -f "$file_path" ]; then
|
||||
cat "$file_path"
|
||||
else
|
||||
echo "{}"
|
||||
fi
|
||||
}
|
||||
|
||||
write_json_file() {
|
||||
local file_path="$1"
|
||||
local json_content="$2"
|
||||
local temp_file="$file_path.tmp.$$"
|
||||
|
||||
printf '%s' "$json_content" > "$temp_file"
|
||||
|
||||
if ! python3 -c "import json; json.load(open('$temp_file'))" 2>/dev/null; then
|
||||
echo "Error: write_json_file would create malformed JSON: $file_path" >&2
|
||||
rm -f "$temp_file"
|
||||
return 1
|
||||
fi
|
||||
|
||||
mv "$temp_file" "$file_path"
|
||||
}
|
||||
|
||||
get_json_value() {
|
||||
local file_path="$1"
|
||||
local key="$2"
|
||||
local default="${3:-}"
|
||||
|
||||
if [ ! -f "$file_path" ]; then
|
||||
echo "$default"
|
||||
return
|
||||
fi
|
||||
|
||||
python3 -c "import json; print(json.load(open('$file_path')).get('$key', '$default'))" 2>/dev/null || echo "$default"
|
||||
}
|
||||
|
||||
set_json_value() {
|
||||
local file_path="$1"
|
||||
local key="$2"
|
||||
local value="$3"
|
||||
|
||||
if [ ! -f "$file_path" ]; then
|
||||
printf '{"%s": "%s"}\n' "$key" "$value" > "$file_path"
|
||||
return
|
||||
fi
|
||||
|
||||
python3 << PYEOF
|
||||
import json
|
||||
import sys
|
||||
|
||||
file_path = "$file_path"
|
||||
key = "$key"
|
||||
value = "$value"
|
||||
|
||||
try:
|
||||
with open(file_path, 'r') as f:
|
||||
data = json.load(f)
|
||||
except:
|
||||
data = {}
|
||||
|
||||
data[key] = value
|
||||
|
||||
with open(file_path, 'w') as f:
|
||||
json.dump(data, f, indent=2)
|
||||
|
||||
print(f"Set $key = $value in $file_path")
|
||||
PYEOF
|
||||
}
|
||||
|
||||
update_session_pr_url() {
|
||||
local issue_ref="$1"
|
||||
local pr_url="$2"
|
||||
|
||||
local session_file=$(get_session_for_issue "$issue_ref")
|
||||
if [ -z "$session_file" ] || [ "$session_file" = "null" ]; then
|
||||
echo "Error: No session found for '$issue_ref'" >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
local session_path="$SESSIONS_DIR/$session_file"
|
||||
if [ ! -f "$session_path" ]; then
|
||||
echo "Error: Session file not found: $session_path" >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
python3 << PYEOF
|
||||
import json
|
||||
|
||||
session_path = "$session_path"
|
||||
pr_url = "$pr_url"
|
||||
|
||||
with open(session_path, 'r') as f:
|
||||
session = json.load(f)
|
||||
|
||||
session['pr_url'] = pr_url
|
||||
|
||||
with open(session_path, 'w') as f:
|
||||
json.dump(session, f, indent=2)
|
||||
|
||||
print(f"Updated PR URL for $issue_ref: $pr_url")
|
||||
PYEOF
|
||||
}
|
||||
|
||||
# Convert issue ref to session filename
|
||||
issue_ref_to_filename() {
|
||||
local issue_ref="$1"
|
||||
echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/'
|
||||
}
|
||||
|
||||
# Convert session filename back to issue ref
|
||||
filename_to_issue_ref() {
|
||||
local filename="$1"
|
||||
local name="${filename%.json}"
|
||||
echo "$name" | sed 's-\([0-9]*\)$-#\1-' | sed 's/-/\//g'
|
||||
}
|
||||
|
||||
# Add notification to notifications file
|
||||
kugetsu_add_notification() {
|
||||
local type="$1"
|
||||
local message="$2"
|
||||
local issue_ref="${3:-}"
|
||||
local gitea_url="${4:-}"
|
||||
|
||||
mkdir -p "$(dirname "$NOTIFICATIONS_FILE")"
|
||||
|
||||
python3 << PYEOF
|
||||
import json
|
||||
import os
|
||||
from datetime import datetime
|
||||
|
||||
notification = {
|
||||
"type": "$type",
|
||||
"message": "$message",
|
||||
"issue_ref": "$issue_ref" if "$issue_ref" else None,
|
||||
"gitea_url": "$gitea_url" if "$gitea_url" else None,
|
||||
"timestamp": datetime.now().isoformat(),
|
||||
"read": False
|
||||
}
|
||||
|
||||
file_path = os.path.expanduser("$NOTIFICATIONS_FILE")
|
||||
notifications = []
|
||||
|
||||
if os.path.exists(file_path):
|
||||
try:
|
||||
with open(file_path, 'r') as f:
|
||||
notifications = json.load(f)
|
||||
except:
|
||||
notifications = []
|
||||
|
||||
notifications.append(notification)
|
||||
|
||||
with open(file_path, 'w') as f:
|
||||
json.dump(notifications, f, indent=2)
|
||||
|
||||
print("Notification added")
|
||||
PYEOF
|
||||
}
|
||||
|
||||
# Update queue item state
|
||||
update_queue_item_state() {
|
||||
local queue_id="$1"
|
||||
local new_state="$2"
|
||||
local session_id="${3:-}"
|
||||
local pid="${4:-}"
|
||||
|
||||
local item_file="$QUEUE_ITEMS_DIR/${queue_id}.json"
|
||||
if [ ! -f "$item_file" ]; then
|
||||
echo "Error: Queue item not found: $queue_id" >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
local issue_ref=$(python3 -c "import json; print(json.load(open('$item_file')).get('issue_ref', ''))" 2>/dev/null || echo "")
|
||||
|
||||
python3 << PYEOF
|
||||
import json
|
||||
from datetime import datetime
|
||||
|
||||
item_file = "$item_file"
|
||||
new_state = "$new_state"
|
||||
session_id = "$session_id"
|
||||
pid = "$pid"
|
||||
|
||||
with open(item_file, 'r') as f:
|
||||
item = json.load(f)
|
||||
|
||||
item['state'] = new_state
|
||||
|
||||
if new_state == "notified":
|
||||
item['notified_at'] = datetime.now().isoformat() + "Z"
|
||||
if session_id:
|
||||
item['opencode_session_id'] = session_id
|
||||
if pid:
|
||||
item['pid'] = int(pid) if pid.isdigit() else None
|
||||
elif new_state == "completed":
|
||||
item['completed_at'] = datetime.now().isoformat() + "Z"
|
||||
elif new_state == "error":
|
||||
item['error'] = datetime.now().isoformat() + "Z"
|
||||
|
||||
with open(item_file, 'w') as f:
|
||||
json.dump(item, f, indent=2)
|
||||
|
||||
print(f"Updated $queue_id to state: $new_state")
|
||||
PYEOF
|
||||
|
||||
if [ "$new_state" = "completed" ]; then
|
||||
kugetsu_add_notification "task_completed" "Task completed: $issue_ref" "$issue_ref"
|
||||
elif [ "$new_state" = "error" ]; then
|
||||
kugetsu_add_notification "task_error" "Task error: $issue_ref" "$issue_ref"
|
||||
fi
|
||||
}
|
||||
@@ -1,13 +1,10 @@
|
||||
#!/bin/bash
|
||||
# kugetsu installation script
|
||||
# Installs kugetsu CLI and optionally sets up Phase 3a Chat Agent
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
KUGETSU_DIR="${KUGETSU_DIR:-$HOME/.kugetsu}"
|
||||
BIN_DIR="${BIN_DIR:-$HOME/.local/bin}"
|
||||
BIN_DIR="$KUGETSU_DIR/bin"
|
||||
|
||||
echo "Installing kugetsu..."
|
||||
echo "Installing kugetsu to $KUGETSU_DIR..."
|
||||
|
||||
mkdir -p "$BIN_DIR"
|
||||
|
||||
@@ -16,48 +13,41 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
cp "$SCRIPT_DIR/kugetsu" "$BIN_DIR/kugetsu"
|
||||
chmod +x "$BIN_DIR/kugetsu"
|
||||
|
||||
echo "kugetsu installed at: $BIN_DIR/kugetsu"
|
||||
|
||||
add_to_shell() {
|
||||
local rc_file="$1"
|
||||
local export_line="export PATH=\"\$HOME/.local/bin:\$PATH\""
|
||||
local export_line="export PATH=\"\$HOME/.kugetsu/bin:\$PATH\""
|
||||
|
||||
if [ -f "$rc_file" ]; then
|
||||
if grep -q "$export_line" "$rc_file" 2>/dev/null; then
|
||||
echo "$rc_file already has .local/bin in PATH"
|
||||
echo "$rc_file already has kugetsu in PATH"
|
||||
else
|
||||
echo "" >> "$rc_file"
|
||||
echo "# kugetsu and other tools" >> "$rc_file"
|
||||
echo "# kugetsu - opencode session manager" >> "$rc_file"
|
||||
echo "$export_line" >> "$rc_file"
|
||||
echo "Added to $rc_file"
|
||||
fi
|
||||
else
|
||||
echo "" >> "$rc_file"
|
||||
echo "# kugetsu - opencode session manager" >> "$rc_file"
|
||||
echo "$export_line" >> "$rc_file"
|
||||
echo "Created $rc_file with kugetsu PATH"
|
||||
fi
|
||||
}
|
||||
|
||||
add_to_shell "$HOME/.bashrc"
|
||||
add_to_shell "$HOME/.zshrc"
|
||||
|
||||
echo ""
|
||||
echo "=== Verifying installation ==="
|
||||
"$BIN_DIR/kugetsu" help | head -10
|
||||
echo ""
|
||||
echo "Installation complete!"
|
||||
|
||||
echo ""
|
||||
echo "=== Phase 3a Chat Agent Setup (Optional) ==="
|
||||
echo "To also install the Chat Agent skills for Phase 3a:"
|
||||
echo "Run this to start using kugetsu immediately:"
|
||||
echo " export PATH=\"\$HOME/.kugetsu/bin:\$PATH\""
|
||||
echo ""
|
||||
echo " 1. Link skills to Hermes:"
|
||||
echo " mkdir -p ~/.hermes/skills/kugetsu-chat"
|
||||
echo " ln -sf /path/to/kugetsu/skills/kugetsu-chat ~/.hermes/skills/"
|
||||
echo "Or start a new shell."
|
||||
echo ""
|
||||
echo " 2. Install Chat Agent SOUL:"
|
||||
echo " cp /path/to/kugetsu/skills/kugetsu-chat/SOUL.md ~/.hermes/SOUL-chat.md"
|
||||
echo ""
|
||||
echo " 3. Initialize kugetsu (requires TTY):"
|
||||
echo " kugetsu init"
|
||||
echo ""
|
||||
echo " 4. Verify setup:"
|
||||
echo " kugetsu status"
|
||||
echo ""
|
||||
echo "See docs/phase3a-setup.md for full installation guide."
|
||||
echo "Usage:"
|
||||
echo " kugetsu start <session_id> <message> Start a new session"
|
||||
echo " kugetsu list List sessions"
|
||||
echo " kugetsu resume <session_id> [msg] Resume a session"
|
||||
echo " kugetsu stop <session_id> Stop a session"
|
||||
echo " kugetsu help Show help"
|
||||
|
||||
@@ -1,136 +0,0 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
source "$SCRIPT_DIR/kugetsu-config.sh"
|
||||
|
||||
log() {
|
||||
local level="${1:-}"
|
||||
local component="${2:-}"
|
||||
local message="${3:-}"
|
||||
local timestamp
|
||||
timestamp=$(date -Iseconds)
|
||||
|
||||
case "$level" in
|
||||
info|warn|error|debug) ;;
|
||||
*)
|
||||
echo "Error: log level must be info|warn|error|debug" >&2
|
||||
return 1
|
||||
;;
|
||||
esac
|
||||
|
||||
if [ -z "$message" ]; then
|
||||
message="$component"
|
||||
component="${level}"
|
||||
level="info"
|
||||
fi
|
||||
|
||||
local masked
|
||||
masked=$(mask_sensitive_vars "$message")
|
||||
echo "[$timestamp] $level $component $masked"
|
||||
}
|
||||
|
||||
log_debug() { log "debug" "$1" "${2:-}"; }
|
||||
log_info() { log "info" "$1" "${2:-}"; }
|
||||
log_warn() { log "warn" "$1" "${2:-}"; }
|
||||
log_error() { log "error" "$1" "${2:-}"; }
|
||||
|
||||
cmd_logs() {
|
||||
local count="${1:-10}"
|
||||
|
||||
if [ ! -d "$LOGS_DIR" ]; then
|
||||
echo "No logs found."
|
||||
return
|
||||
fi
|
||||
|
||||
find "$LOGS_DIR" -type f -mtime +7 -delete 2>/dev/null
|
||||
|
||||
ls -lt "$LOGS_DIR" | head -$((count + 1)) | tail -$count | while read line; do
|
||||
echo "$line"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "Recent log contents:"
|
||||
echo "===================="
|
||||
|
||||
for log in $(ls -lt "$LOGS_DIR" | head -$((count + 1)) | tail -$count | awk '{print $NF}'); do
|
||||
if [ -f "$LOGS_DIR/$log" ]; then
|
||||
echo ""
|
||||
echo "--- $log ---"
|
||||
tail -20 "$LOGS_DIR/$log" | while read line; do
|
||||
line=$(strip_ansi_codes "$line")
|
||||
line=$(mask_sensitive_vars "$line")
|
||||
echo " $line"
|
||||
done
|
||||
fi
|
||||
done
|
||||
}
|
||||
|
||||
kugetsu_add_notification() {
|
||||
local notification_type="$1"
|
||||
local message="$2"
|
||||
local issue_ref="${3:-}"
|
||||
local timestamp=$(date -Iseconds)
|
||||
|
||||
mkdir -p "$(dirname "$NOTIFICATIONS_FILE")"
|
||||
|
||||
local notifications="[]"
|
||||
if [ -f "$NOTIFICATIONS_FILE" ]; then
|
||||
notifications=$(cat "$NOTIFICATIONS_FILE")
|
||||
fi
|
||||
|
||||
notifications=$(echo "$notifications" | python3 -c "
|
||||
import json
|
||||
import sys
|
||||
|
||||
notifications = json.load(sys.stdin)
|
||||
new_notification = {
|
||||
'type': '$notification_type',
|
||||
'message': '''$message'''.replace('\"', '\"'),
|
||||
'issue_ref': '$issue_ref' if '$issue_ref' else None,
|
||||
'timestamp': '$timestamp',
|
||||
'read': False
|
||||
}
|
||||
|
||||
notifications.append(new_notification)
|
||||
notifications = notifications[-50:] if len(notifications) > 50 else notifications
|
||||
|
||||
print(json.dumps(notifications, indent=2))
|
||||
")
|
||||
|
||||
echo "$notifications" > "$NOTIFICATIONS_FILE"
|
||||
}
|
||||
|
||||
cmd_notify() {
|
||||
local action="${1:-list}"
|
||||
|
||||
case "$action" in
|
||||
list)
|
||||
if [ ! -f "$NOTIFICATIONS_FILE" ]; then
|
||||
echo "No notifications."
|
||||
return
|
||||
fi
|
||||
|
||||
local notifications=$(cat "$NOTIFICATIONS_FILE")
|
||||
local count=$(echo "$notifications" | python3 -c "import sys, json; n=json.load(sys.stdin); print(sum(1 for x in n if not x.get('read', False)))")
|
||||
|
||||
if [ "$count" -eq 0 ]; then
|
||||
echo "No unread notifications."
|
||||
return
|
||||
fi
|
||||
|
||||
echo "Unread notifications ($count):"
|
||||
echo "$notifications" | python3 -c "import sys, json; [print(f\" [{x.get('timestamp', '')}] {x.get('type', '')}: {x.get('message', '')}\") for x in json.load(sys.stdin) if not x.get('read', False)]"
|
||||
;;
|
||||
clear)
|
||||
if [ -f "$NOTIFICATIONS_FILE" ]; then
|
||||
python3 -c "import json; print(json.dumps([x for x in json.load(open('$NOTIFICATIONS_FILE')) if x.get('read', False)], indent=2))" > "$NOTIFICATIONS_FILE"
|
||||
echo "Cleared unread notifications."
|
||||
fi
|
||||
;;
|
||||
*)
|
||||
echo "Usage: kugetsu notify [list|clear]" >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
}
|
||||
@@ -1,169 +0,0 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
source "$SCRIPT_DIR/kugetsu-config.sh"
|
||||
source "$SCRIPT_DIR/kugetsu-index.sh"
|
||||
source "$SCRIPT_DIR/kugetsu-worktree.sh"
|
||||
source "$SCRIPT_DIR/kugetsu-log.sh"
|
||||
|
||||
load_agent_env "pm-agent"
|
||||
|
||||
acquire_lock() {
|
||||
local issue_ref="$1"
|
||||
local lock_file="$QUEUE_DIR/locks/$(echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/').lock"
|
||||
mkdir -p "$(dirname "$lock_file")"
|
||||
if [ -f "$lock_file" ]; then
|
||||
local pid=$(cat "$lock_file" 2>/dev/null || echo "")
|
||||
if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
|
||||
return 1
|
||||
fi
|
||||
rm -f "$lock_file"
|
||||
fi
|
||||
echo $$ > "$lock_file"
|
||||
return 0
|
||||
}
|
||||
|
||||
release_lock() {
|
||||
local issue_ref="$1"
|
||||
local lock_file="$QUEUE_DIR/locks/$(echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/').lock"
|
||||
rm -f "$lock_file"
|
||||
}
|
||||
|
||||
check_task_completion() {
|
||||
local item="$1"
|
||||
local queue_id=$(basename "$item" .json)
|
||||
|
||||
local item_data=$(read_json_file "$item")
|
||||
local state=$(python3 -c "import json; print(json.load(open('$item')).get('state', ''))" 2>/dev/null)
|
||||
|
||||
[ "$state" = "notified" ] || return 0
|
||||
|
||||
local session_id=$(python3 -c "import json; print(json.load(open('$item')).get('opencode_session_id', ''))" 2>/dev/null)
|
||||
local issue_ref=$(python3 -c "import json; print(json.load(open('$item')).get('issue_ref', ''))" 2>/dev/null)
|
||||
local pid=$(python3 -c "import json; print(json.load(open('$item')).get('pid', ''))" 2>/dev/null)
|
||||
local notified_at=$(python3 -c "import json; print(json.load(open('$item')).get('notified_at', ''))" 2>/dev/null)
|
||||
|
||||
local timed_out=false
|
||||
if [ -n "$notified_at" ]; then
|
||||
local notified_epoch=$(date -d "$notified_at" +%s 2>/dev/null || echo "0")
|
||||
local now_epoch=$(date +%s)
|
||||
local hours_elapsed=$(( (now_epoch - notified_epoch) / 3600 ))
|
||||
if [ "$hours_elapsed" -ge "${TASK_TIMEOUT_HOURS:-1}" ]; then
|
||||
timed_out=true
|
||||
log_warn "queue-daemon" "Task $queue_id ($issue_ref) timed out after ${hours_elapsed}h"
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ "$timed_out" = true ]; then
|
||||
if [ -n "$pid" ] && [ "$pid" != "None" ]; then
|
||||
kill "$pid" 2>/dev/null || true
|
||||
fi
|
||||
if [ -n "$session_id" ]; then
|
||||
opencode session stop "$session_id" 2>/dev/null || true
|
||||
fi
|
||||
update_queue_item_state "$queue_id" "error"
|
||||
log_error "queue-daemon" "Task $queue_id ($issue_ref) marked error — timeout after ${hours_elapsed}h"
|
||||
release_lock "$issue_ref"
|
||||
return
|
||||
fi
|
||||
|
||||
if [ -n "$pid" ] && [ "$pid" != "None" ]; then
|
||||
if ! kill -0 "$pid" 2>/dev/null; then
|
||||
local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$WORKTREES_DIR")
|
||||
local has_commits=false
|
||||
|
||||
if [ -d "$worktree_path" ] && [ -d "$worktree_path/.git" ]; then
|
||||
if [ -n "$(git -C "$worktree_path" log --oneline "$KUGETSU_BASE_BRANCH..HEAD" 2>/dev/null)" ]; then
|
||||
has_commits=true
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ "$has_commits" = true ]; then
|
||||
update_queue_item_state "$queue_id" "completed"
|
||||
echo "Task $queue_id ($issue_ref) completed — new commits found"
|
||||
else
|
||||
update_queue_item_state "$queue_id" "error"
|
||||
echo "Task $queue_id ($issue_ref) marked error — no commits found after session ended"
|
||||
fi
|
||||
release_lock "$issue_ref"
|
||||
fi
|
||||
else
|
||||
if [ -n "$session_id" ] && ! opencode session list 2>/dev/null | grep -q "$session_id"; then
|
||||
local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$WORKTREES_DIR")
|
||||
local has_commits=false
|
||||
|
||||
if [ -d "$worktree_path" ] && [ -d "$worktree_path/.git" ]; then
|
||||
if [ -n "$(git -C "$worktree_path" log --oneline "$KUGETSU_BASE_BRANCH..HEAD" 2>/dev/null)" ]; then
|
||||
has_commits=true
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ "$has_commits" = true ]; then
|
||||
update_queue_item_state "$queue_id" "completed"
|
||||
echo "Task $queue_id ($issue_ref) completed — new commits found"
|
||||
else
|
||||
update_queue_item_state "$queue_id" "error"
|
||||
echo "Task $queue_id ($issue_ref) marked error — no commits found after session ended"
|
||||
fi
|
||||
release_lock "$issue_ref"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
get_session_id_for_issue() {
|
||||
local issue_ref="$1"
|
||||
local session_file=$(issue_ref_to_filename "$issue_ref")
|
||||
local session_path="$SESSIONS_DIR/$session_file"
|
||||
if [ -f "$session_path" ]; then
|
||||
python3 -c "import json; print(json.load(open('$session_path')).get('opencode_session_id', ''))" 2>/dev/null || echo ""
|
||||
else
|
||||
echo ""
|
||||
fi
|
||||
}
|
||||
|
||||
process_task() {
|
||||
local item="$1"
|
||||
local queue_id=$(basename "$item" .json)
|
||||
local issue_ref=$(python3 -c "import json; print(json.load(open('$item')).get('issue_ref', ''))" 2>/dev/null)
|
||||
local message=$(python3 -c "import json; print(json.load(open('$item')).get('message', ''))" 2>/dev/null)
|
||||
|
||||
if ! acquire_lock "$issue_ref"; then
|
||||
echo "Task $queue_id ($issue_ref) skipped — another process is handling it"
|
||||
return
|
||||
fi
|
||||
|
||||
source "$SCRIPT_DIR/kugetsu-session.sh"
|
||||
|
||||
log_file="$LOGS_DIR/delegate-$(date +%s).log"
|
||||
if cmd_continue "$issue_ref" "$message" >> "$log_file" 2>&1; then
|
||||
sleep 1
|
||||
local session_id=$(get_session_id_for_issue "$issue_ref")
|
||||
update_queue_item_state "$queue_id" "notified" "$session_id" ""
|
||||
echo "Task $queue_id continued for $issue_ref"
|
||||
else
|
||||
update_queue_item_state "$queue_id" "error"
|
||||
echo "Task $queue_id ($issue_ref) failed to continue"
|
||||
fi
|
||||
|
||||
release_lock "$issue_ref"
|
||||
}
|
||||
|
||||
while true; do
|
||||
if [ -d "$QUEUE_ITEMS_DIR" ]; then
|
||||
for item in "$QUEUE_ITEMS_DIR"/*.json; do
|
||||
[ -f "$item" ] || continue
|
||||
check_task_completion "$item"
|
||||
done
|
||||
|
||||
for item in "$QUEUE_ITEMS_DIR"/*.json; do
|
||||
[ -f "$item" ] || continue
|
||||
state=$(python3 -c "import json; print(json.load(open('$item')).get('state', ''))" 2>/dev/null)
|
||||
if [ "$state" = "pending" ]; then
|
||||
process_task "$item"
|
||||
fi
|
||||
done
|
||||
fi
|
||||
sleep "${QUEUE_DAEMON_INTERVAL_MINUTES:-5}m"
|
||||
done
|
||||
@@ -1,803 +0,0 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
# Source required modules for session management functions
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
source "$SCRIPT_DIR/kugetsu-config.sh"
|
||||
source "$SCRIPT_DIR/kugetsu-index.sh"
|
||||
source "$SCRIPT_DIR/kugetsu-worktree.sh"
|
||||
source "$SCRIPT_DIR/kugetsu-log.sh"
|
||||
|
||||
count_active_dev_sessions() {
|
||||
local count=0
|
||||
if [ -d "$SESSIONS_DIR" ]; then
|
||||
for session_file in "$SESSIONS_DIR"/*.json; do
|
||||
if [ -f "$session_file" ]; then
|
||||
local filename
|
||||
filename=$(basename "$session_file")
|
||||
if [ "$filename" != "base.json" ] && [ "$filename" != "pm-agent.json" ]; then
|
||||
count=$((count + 1))
|
||||
fi
|
||||
fi
|
||||
done
|
||||
fi
|
||||
echo "$count"
|
||||
}
|
||||
|
||||
cmd_init() {
|
||||
local force=false
|
||||
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--force)
|
||||
force=true
|
||||
;;
|
||||
*)
|
||||
;;
|
||||
esac
|
||||
shift
|
||||
done
|
||||
|
||||
ensure_dirs
|
||||
|
||||
if [ ! -f "$KUGETSU_DIR/config" ]; then
|
||||
cat > "$KUGETSU_DIR/config" << 'EOF'
|
||||
# User configuration overrides
|
||||
# Values set here take precedence over defaults
|
||||
# Changes take effect immediately (no re-init needed)
|
||||
|
||||
# Max concurrent dev agents (default: 3)
|
||||
# MAX_CONCURRENT_AGENTS=5
|
||||
|
||||
# Git server configurations
|
||||
# Format: GIT_SERVERS["hostname"]="https://hostname"
|
||||
declare -A GIT_SERVERS
|
||||
GIT_SERVERS["github.com"]="https://github.com"
|
||||
GIT_SERVERS["git.fbrns.co"]="https://git.fbrns.co"
|
||||
DEFAULT_GIT_SERVER="github.com"
|
||||
EOF
|
||||
echo "Created config file: $KUGETSU_DIR/config"
|
||||
fi
|
||||
|
||||
mkdir -p "$ENV_DIR"
|
||||
if [ ! -f "$ENV_DIR/default.env" ]; then
|
||||
cat > "$ENV_DIR/default.env" << 'EOF'
|
||||
# Environment variables for agents
|
||||
# Copy this file to <agent-type>.env (e.g., pm-agent.env, dev.env)
|
||||
# and set your tokens and configuration
|
||||
|
||||
# Required: Gitea token for API access
|
||||
# GITEA_TOKEN=your_gitea_token_here
|
||||
|
||||
# Optional: GitHub token (if using GitHub)
|
||||
# GITHUB_TOKEN=your_github_token_here
|
||||
|
||||
# Optional: GitLab token (if using GitLab)
|
||||
# GITLAB_TOKEN=your_gitlab_token_here
|
||||
EOF
|
||||
echo "Created env template: $ENV_DIR/default.env"
|
||||
fi
|
||||
|
||||
local existing_base=$(get_base_session_id)
|
||||
local existing_pm=$(get_pm_agent_session_id)
|
||||
|
||||
if [ -n "$existing_base" ] && [ "$existing_base" != "null" ]; then
|
||||
if [ "$force" = true ]; then
|
||||
echo "Warning: Reinitializing sessions (force mode)" >&2
|
||||
echo "Destroying all sessions, worktrees, and logs..." >&2
|
||||
cmd_destroy --base -y 2>/dev/null || true
|
||||
cmd_destroy --pm-agent -y 2>/dev/null || true
|
||||
rm -f "$LOGS_DIR"/*.log 2>/dev/null || true
|
||||
else
|
||||
echo "Error: Base session already exists: $existing_base" >&2
|
||||
echo "Use --force to reinitialize" >&2
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
if ! test -t 0; then
|
||||
echo "Error: init requires a terminal (TTY)" >&2
|
||||
echo "Please run this command in an interactive shell" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Starting TUI to create base session..."
|
||||
echo "Press Ctrl+C to cancel or wait for session to be created"
|
||||
sleep 2
|
||||
|
||||
local before_sessions=$(opencode session list 2>/dev/null | grep -E '^ses_' | awk '{print $1}' || true)
|
||||
|
||||
opencode
|
||||
|
||||
local after_sessions=$(opencode session list 2>/dev/null | grep -E '^ses_' | awk '{print $1}' || true)
|
||||
local session_ids=""
|
||||
while IFS= read -r line; do
|
||||
local sid=$(echo "$line" | awk '{print $1}')
|
||||
if [ -n "$sid" ] && ! echo "$before_sessions" | grep -q "^${sid}$"; then
|
||||
session_ids="$sid"
|
||||
break
|
||||
fi
|
||||
done <<< "$after_sessions"
|
||||
|
||||
if [ -z "$session_ids" ]; then
|
||||
echo "Error: Could not find newly created session" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "$session_ids" > "$SESSIONS_DIR/base.json"
|
||||
set_base_in_index "$session_ids"
|
||||
|
||||
echo "Base session created: $session_ids"
|
||||
echo "Starting PM agent..."
|
||||
|
||||
before_sessions="$after_sessions"
|
||||
|
||||
opencode
|
||||
|
||||
after_sessions=$(opencode session list 2>/dev/null | grep -E '^ses_' | awk '{print $1}' || true)
|
||||
local pm_session_ids=""
|
||||
while IFS= read -r line; do
|
||||
local sid=$(echo "$line" | awk '{print $1}')
|
||||
if [ -n "$sid" ] && ! echo "$before_sessions" | grep -q "^${sid}$"; then
|
||||
pm_session_ids="$sid"
|
||||
break
|
||||
fi
|
||||
done <<< "$after_sessions"
|
||||
|
||||
if [ -z "$pm_session_ids" ]; then
|
||||
echo "Warning: Could not find separate PM agent session" >&2
|
||||
pm_session_ids="$session_ids"
|
||||
fi
|
||||
|
||||
echo "$pm_session_ids" > "$SESSIONS_DIR/pm-agent.json"
|
||||
set_pm_agent_in_index "$pm_session_ids"
|
||||
|
||||
load_agent_env "pm-agent"
|
||||
|
||||
local pm_system_prompt=""
|
||||
if [ -f "$KUGETSU_DIR/pm-agent.md" ]; then
|
||||
pm_system_prompt=$(cat "$KUGETSU_DIR/pm-agent.md")
|
||||
echo "Injecting PM agent system prompt from $KUGETSU_DIR/pm-agent.md"
|
||||
fi
|
||||
|
||||
echo "PM agent session created: $pm_session_ids"
|
||||
echo ""
|
||||
echo "kugetsu initialized successfully!"
|
||||
echo " Base session: $session_ids"
|
||||
echo " PM agent: $pm_session_ids"
|
||||
}
|
||||
|
||||
extract_issue_ref_from_message() {
|
||||
local message="$1"
|
||||
|
||||
if [ -z "$message" ]; then
|
||||
echo ""
|
||||
return
|
||||
fi
|
||||
|
||||
if [[ "$message" =~ ^([a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+#[0-9]+) ]]; then
|
||||
echo "${BASH_REMATCH[1]}"
|
||||
return
|
||||
fi
|
||||
|
||||
if [[ "$message" =~ (https?://)?([a-zA-Z0-9.-]+)/([a-zA-Z0-9._-]+)/([a-zA-Z0-9._-]+)/(issues|pull)/([0-9]+) ]]; then
|
||||
local instance="${BASH_REMATCH[2]}"
|
||||
local owner="${BASH_REMATCH[3]}"
|
||||
local repo="${BASH_REMATCH[4]}"
|
||||
local num="${BASH_REMATCH[6]}"
|
||||
echo "${instance}/${owner}/${repo}#${num}"
|
||||
return
|
||||
fi
|
||||
|
||||
echo ""
|
||||
}
|
||||
|
||||
cmd_delegate() {
|
||||
local message="${1:-}"
|
||||
|
||||
if [ -z "$message" ]; then
|
||||
echo "Error: message is required" >&2
|
||||
echo "Usage: kugetsu delegate <message>" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
local issue_ref=$(extract_issue_ref_from_message "$message")
|
||||
|
||||
if [ -n "$issue_ref" ] && [[ "$issue_ref" =~ \#[0-9]+$ ]]; then
|
||||
# Enqueue for daemon to process via cmd_start/cmd_continue
|
||||
enqueue_task "$issue_ref" "$message"
|
||||
return
|
||||
fi
|
||||
|
||||
# No issue ref detected — fork a new session from base session
|
||||
local base_session=$(get_base_session_id)
|
||||
if [ -z "$base_session" ] || [ "$base_session" = "null" ]; then
|
||||
echo "Error: Base session not found. Run 'kugetsu init' first." >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
mkdir -p "$LOGS_DIR"
|
||||
local log_file="$LOGS_DIR/delegate-$(date +%s).log"
|
||||
load_agent_env "pm-agent"
|
||||
|
||||
local new_session=$(create_session "$base_session")
|
||||
if [ -z "$new_session" ]; then
|
||||
echo "Error: Failed to create session" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
local msg_file="$LOGS_DIR/msg-$new_session.txt"
|
||||
printf '%s' "$message" > "$msg_file"
|
||||
nohup sh -c "GITEA_TOKEN='${GITEA_TOKEN:-}' opencode run '@$msg_file' --session '$new_session'" >> "$log_file" 2>&1 &
|
||||
echo "Delegated to new session (logged to $(basename "$log_file"))"
|
||||
}
|
||||
|
||||
create_session() {
|
||||
local base_session="${1:-$base_session_id}"
|
||||
|
||||
if [ -z "$base_session" ] || [ "$base_session" = "null" ]; then
|
||||
echo "Error: base session not found. Run 'kugetsu init' first." >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
local before_file
|
||||
before_file="$KUGETSU_DIR/sessions/before$$.json"
|
||||
local after_file
|
||||
after_file="$KUGETSU_DIR/sessions/after$$.json"
|
||||
|
||||
opencode session list --format=json > "$before_file" 2>/dev/null || printf '{}' > "$before_file"
|
||||
|
||||
local fork_success=false
|
||||
local attempt=0
|
||||
local max_attempts="${NETWORK_RETRY_ATTEMPTS:-3}"
|
||||
|
||||
while [ $attempt -lt $max_attempts ] && [ "$fork_success" = false ]; do
|
||||
attempt=$((attempt + 1))
|
||||
if opencode run --fork --session "$base_session" "new session" >/dev/null 2>&1; then
|
||||
fork_success=true
|
||||
elif [ $attempt -lt $max_attempts ]; then
|
||||
log "warn" "create_session" "Fork attempt $attempt failed, retrying..."
|
||||
sleep "$((attempt * 2))"
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "$fork_success" = false ]; then
|
||||
log "error" "create_session" "Failed to fork session after $max_attempts attempts"
|
||||
rm -f "$before_file" "$after_file"
|
||||
return 1
|
||||
fi
|
||||
|
||||
sleep 1
|
||||
|
||||
opencode session list --format=json > "$after_file" 2>/dev/null || printf '{}' > "$after_file"
|
||||
|
||||
local new_session_id
|
||||
new_session_id=$(python3 << PYEOF
|
||||
import json
|
||||
|
||||
with open("$before_file", 'r') as f:
|
||||
before = json.load(f)
|
||||
with open("$after_file", 'r') as f:
|
||||
after = json.load(f)
|
||||
|
||||
before_ids = set(s['id'] for s in before)
|
||||
for s in after:
|
||||
if s['id'] not in before_ids:
|
||||
print(s['id'])
|
||||
break
|
||||
PYEOF
|
||||
)
|
||||
|
||||
rm -f "$before_file" "$after_file"
|
||||
|
||||
echo "$new_session_id"
|
||||
}
|
||||
|
||||
build_dev_agent_message() {
|
||||
local issue_ref="$1"
|
||||
local user_message="${2:-}"
|
||||
|
||||
local instance=$(echo "$issue_ref" | cut -d'/' -f1 | cut -d'#' -f1)
|
||||
local owner=$(echo "$issue_ref" | cut -d'/' -f2)
|
||||
local repo=$(echo "$issue_ref" | cut -d'/' -f3 | cut -d'#' -f1)
|
||||
local number=$(echo "$issue_ref" | grep -oE '#[0-9]+$' | tr -d '#')
|
||||
local worktree_path=$(issue_ref_to_worktree_path "$issue_ref")
|
||||
|
||||
local conflict_check=""
|
||||
local review_notes=""
|
||||
local delegator_header=""
|
||||
local delegator_footer=""
|
||||
if [ -n "$user_message" ]; then
|
||||
conflict_check=" - CRITICAL: Check if PR has merge conflicts before asking for review:
|
||||
- Use: curl -s \"https://$instance/api/v1/repos/$owner/$repo/pulls/$number\" -H \"Authorization: Bearer \$GITEA_TOKEN\"
|
||||
- If \"mergeable\": false, there ARE conflicts - you MUST resolve them FIRST
|
||||
- To resolve: cd to worktree, git fetch origin, git rebase origin/main, resolve conflicts, git rebase --continue, git push --force-with-lease
|
||||
- Only after resolving conflicts (mergeable: true) can you ask for review"
|
||||
delegator_header="IMPORTANT: Follow the workflow below as your guideline, but prioritize the delegator's message.
|
||||
|
||||
Workflow:"
|
||||
delegator_footer="
|
||||
|
||||
Delegator's message:
|
||||
$user_message"
|
||||
else
|
||||
review_notes=" - IMPORTANT: After listing reviews, READ the review comments and incorporate feedback
|
||||
- Check for review state: \"APPROVED\" means ready to merge, \"COMMENT\" means feedback to address"
|
||||
delegator_header="Workflow:"
|
||||
fi
|
||||
|
||||
cat <<EOF
|
||||
You are assigned to work on $issue_ref.
|
||||
|
||||
$delegator_header
|
||||
1. Read the issue at $instance/$owner/$repo/issues/$number AND all comments on that issue
|
||||
2. Check if a PR already exists for this issue
|
||||
- If PR exists and is open, review it and learn from it
|
||||
$conflict_check
|
||||
- If PR makes sense to continue, work on it instead
|
||||
- If PR is not worth continuing, create a new branch/PR but explain in PR description why you're creating a new one instead of continuing the existing PR
|
||||
3. Read README.md (if exists) to understand the general concept of this repository
|
||||
4. Read CONTRIBUTING.md (if exists) to understand how to contribute
|
||||
- If CONTRIBUTING.md doesn't exist, follow steps 5-9 as your guideline
|
||||
5. Explore the repository to understand the codebase
|
||||
6. If anything is unclear, post a comment on the issue asking for clarification before implementing
|
||||
7. Implement the solution
|
||||
8. Create a branch named fix/issue-$number and implement the fix
|
||||
9. Create a PR when the implementation is complete using: tea pr create --repo $owner/$repo --title "Your PR title" --body "PR description"
|
||||
- Make sure you are logged in with: tea login add --name gitea --token \$GITEA_TOKEN --url https://$instance
|
||||
- If tea is not available, use: curl -X POST "https://$instance/api/v1/repos/$owner/$repo/pulls" -H "Authorization: Bearer \$GITEA_TOKEN" -H "Content-Type: application/json" -d '{"title":"PR Title","head":"branch-name","base":"main","body":"PR description"}'
|
||||
|
||||
Tools for PR interaction:
|
||||
- Post issue/PR comment: curl -X POST "https://$instance/api/v1/repos/$owner/$repo/issues/$number/comments" -H "Authorization: Bearer \$GITEA_TOKEN" -H "Content-Type: application/json" -d '{"body":"Your comment"}'
|
||||
- List PR comments: curl -s "https://$instance/api/v1/repos/$owner/$repo/issues/$number/comments" -H "Authorization: Bearer \$GITEA_TOKEN"
|
||||
- List PR reviews: curl -s "https://$instance/api/v1/repos/$owner/$repo/pulls/$number/reviews" -H "Authorization: Bearer \$GITEA_TOKEN"
|
||||
$review_notes
|
||||
- Merge PR (only with approval): tea pr merge --repo $owner/$repo $number --style merge
|
||||
- MERGING requires approval first! Check for: approval in reviews, OR "lgtm"/"approved" in comments
|
||||
- If no approval, ask reviewer to approve first before merging
|
||||
$delegator_footer
|
||||
|
||||
Work directory: $worktree_path
|
||||
EOF
|
||||
}
|
||||
|
||||
ensure_worktree() {
|
||||
local issue_ref="$1"
|
||||
|
||||
if worktree_exists "$issue_ref" "$WORKTREES_DIR"; then
|
||||
log "info" "ensure_worktree" "Worktree already exists for $issue_ref"
|
||||
echo "existed"
|
||||
return 0
|
||||
fi
|
||||
|
||||
local base_session_id=$(get_base_session_id)
|
||||
if [ -z "$base_session_id" ] || [ "$base_session_id" = "null" ]; then
|
||||
log "error" "ensure_worktree" "Base session not found for $issue_ref"
|
||||
echo "error"
|
||||
return 1
|
||||
fi
|
||||
|
||||
local active_count=$(count_active_dev_sessions)
|
||||
if [ "$active_count" -ge "${MAX_CONCURRENT_AGENTS:-3}" ]; then
|
||||
log "error" "ensure_worktree" "Max concurrent agents reached for $issue_ref"
|
||||
echo "max_agents"
|
||||
return 2
|
||||
fi
|
||||
|
||||
if create_worktree "$issue_ref" "$WORKTREES_DIR" 2>&1 | tee >(cat >&2); then
|
||||
log "info" "ensure_worktree" "Created worktree for $issue_ref"
|
||||
echo "created"
|
||||
return 0
|
||||
else
|
||||
log "error" "ensure_worktree" "Failed to create worktree for $issue_ref"
|
||||
echo "error"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
ensure_session() {
|
||||
local issue_ref="$1"
|
||||
|
||||
local session_file=$(issue_ref_to_filename "$issue_ref")
|
||||
local session_path="$SESSIONS_DIR/$session_file"
|
||||
|
||||
local worktree_exists=false
|
||||
if worktree_exists "$issue_ref" "$WORKTREES_DIR"; then
|
||||
worktree_exists=true
|
||||
fi
|
||||
|
||||
local session_exists=false
|
||||
if [ -f "$session_path" ]; then
|
||||
session_exists=true
|
||||
fi
|
||||
|
||||
if [ "$worktree_exists" = true ] && [ "$session_exists" = true ]; then
|
||||
log "info" "ensure_session" "Session already exists for $issue_ref"
|
||||
echo "continued"
|
||||
return 0
|
||||
fi
|
||||
|
||||
if [ "$worktree_exists" = false ] && [ "$session_exists" = true ]; then
|
||||
log "warn" "ensure_session" "Session exists but worktree is missing. Removing stale session..."
|
||||
rm -f "$session_path"
|
||||
remove_issue_from_index "$issue_ref"
|
||||
session_exists=false
|
||||
fi
|
||||
|
||||
if [ "$worktree_exists" = false ]; then
|
||||
local wt_status=$(ensure_worktree "$issue_ref")
|
||||
if [ "$wt_status" != "created" ] && [ "$wt_status" != "existed" ]; then
|
||||
log "error" "ensure_session" "Failed to ensure worktree for $issue_ref"
|
||||
echo "error"
|
||||
return 1
|
||||
fi
|
||||
fi
|
||||
|
||||
local base_session_id=$(get_base_session_id)
|
||||
if [ -z "$base_session_id" ] || [ "$base_session_id" = "null" ]; then
|
||||
log "error" "ensure_session" "Base session not found for $issue_ref"
|
||||
echo "error"
|
||||
return 1
|
||||
fi
|
||||
|
||||
local new_session_id=$(create_session "$base_session_id")
|
||||
|
||||
if [ -z "$new_session_id" ]; then
|
||||
log "error" "ensure_session" "Could not create session for $issue_ref"
|
||||
echo "error"
|
||||
return 1
|
||||
fi
|
||||
|
||||
local worktree_path=$(issue_ref_to_worktree_path "$issue_ref")
|
||||
|
||||
printf '{"type": "forked", "issue_ref": "%s", "opencode_session_id": "%s", "worktree_path": "%s", "created_at": "%s", "state": "idle"}\n' \
|
||||
"$issue_ref" "$new_session_id" "$worktree_path" "$(date -Iseconds)" > "$SESSIONS_DIR/$session_file"
|
||||
|
||||
add_issue_to_index "$issue_ref" "$session_file"
|
||||
|
||||
log "info" "ensure_session" "Created session for $issue_ref: $new_session_id"
|
||||
echo "created"
|
||||
return 0
|
||||
}
|
||||
|
||||
fork_agent() {
|
||||
local session_id="$1"
|
||||
local worktree_path="$2"
|
||||
local message="$3"
|
||||
|
||||
if [ -z "$worktree_path" ] || [ ! -d "$worktree_path" ]; then
|
||||
log "error" "fork_agent" "Invalid worktree path: $worktree_path"
|
||||
return 1
|
||||
fi
|
||||
|
||||
load_agent_env "dev"
|
||||
|
||||
cd "$worktree_path"
|
||||
local sanitized_id=$(echo "$session_id" | sed 's/[^a-zA-Z0-9_-]/_/g')
|
||||
mkdir -p "$worktree_path/.kugetsu"
|
||||
if [ ! -f "$worktree_path/.gitignore" ] || ! grep -q "^.kugetsu/" "$worktree_path/.gitignore" ]; then
|
||||
echo ".kugetsu/" >> "$worktree_path/.gitignore" 2>/dev/null || true
|
||||
fi
|
||||
local msg_file="$worktree_path/.kugetsu/msg.txt"
|
||||
printf '%s' "$message" > "$msg_file"
|
||||
nohup sh -c "GITEA_TOKEN='${GITEA_TOKEN:-}' opencode run '@$msg_file' --session '$session_id'" >> "$LOGS_DIR/dev-$sanitized_id.log" 2>&1 &
|
||||
|
||||
log "info" "fork_agent" "Forked agent for session $session_id in $worktree_path"
|
||||
return 0
|
||||
}
|
||||
|
||||
cmd_start() {
|
||||
cmd_continue "$@"
|
||||
}
|
||||
|
||||
cmd_continue() {
|
||||
local issue_ref="${1:-}"
|
||||
local message="${2:-}"
|
||||
|
||||
if [ -z "$issue_ref" ]; then
|
||||
echo "Error: issue ref is required" >&2
|
||||
echo "Usage: kugetsu continue <issue-ref> [message]" >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
validate_issue_ref "$issue_ref" || return 1
|
||||
|
||||
if [ -z "$message" ]; then
|
||||
message=$(build_dev_agent_message "$issue_ref" "")
|
||||
else
|
||||
message=$(build_dev_agent_message "$issue_ref" "$message")
|
||||
fi
|
||||
|
||||
local worktree_status=$(ensure_worktree "$issue_ref")
|
||||
if [ "$worktree_status" = "max_agents" ]; then
|
||||
echo "Error: Max concurrent agents reached for '$issue_ref'" >&2
|
||||
return 2
|
||||
fi
|
||||
if [ "$worktree_status" = "error" ]; then
|
||||
echo "Error: Failed to ensure worktree for '$issue_ref'" >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
local session_status=$(ensure_session "$issue_ref")
|
||||
if [ "$session_status" = "error" ]; then
|
||||
echo "Error: Failed to ensure session for '$issue_ref'" >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
kugetsu_context_dump "$issue_ref" "$message" "$(issue_ref_to_branch_name "$issue_ref")"
|
||||
|
||||
local session_file=$(issue_ref_to_filename "$issue_ref")
|
||||
local session_path="$SESSIONS_DIR/$session_file"
|
||||
local opencode_session_id=$(python3 -c "import json; print(json.load(open('$session_path')).get('opencode_session_id', ''))" 2>/dev/null || echo "")
|
||||
local worktree_path=$(python3 -c "import json; print(json.load(open('$session_path')).get('worktree_path', ''))" 2>/dev/null || echo "")
|
||||
|
||||
fork_agent "$opencode_session_id" "$worktree_path" "$message" || return 1
|
||||
|
||||
log "info" "cmd_continue" "Result for $issue_ref: worktree=$worktree_status session=$session_status fork=forked"
|
||||
|
||||
echo "Session continued for '$issue_ref': $opencode_session_id"
|
||||
echo "Worktree: $worktree_path"
|
||||
echo "${worktree_status}-${session_status}-forked"
|
||||
}
|
||||
|
||||
cmd_list() {
|
||||
echo "=== kugetsu sessions ==="
|
||||
echo ""
|
||||
|
||||
local base_id=$(get_base_session_id)
|
||||
if [ -n "$base_id" ] && [ "$base_id" != "null" ]; then
|
||||
echo "Base session: $base_id"
|
||||
else
|
||||
echo "Base session: not initialized"
|
||||
fi
|
||||
|
||||
local pm_id=$(get_pm_agent_session_id)
|
||||
if [ -n "$pm_id" ] && [ "$pm_id" != "null" ]; then
|
||||
echo "PM agent: $pm_id"
|
||||
else
|
||||
echo "PM agent: not initialized"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "Issue sessions:"
|
||||
|
||||
if [ -d "$SESSIONS_DIR" ]; then
|
||||
for session_file in "$SESSIONS_DIR"/*.json; do
|
||||
if [ -f "$session_file" ]; then
|
||||
local filename=$(basename "$session_file")
|
||||
if [ "$filename" != "base.json" ] && [ "$filename" != "pm-agent.json" ]; then
|
||||
local issue_ref=$(filename_to_issue_ref "$filename")
|
||||
local opencode_sid=$(python3 -c "import json; print(json.load(open('$session_file')).get('opencode_session_id', 'unknown'))" 2>/dev/null || echo "unknown")
|
||||
local state=$(python3 -c "import json; print(json.load(open('$session_file')).get('state', 'unknown'))" 2>/dev/null || echo "unknown")
|
||||
local worktree_path=$(python3 -c "import json; print(json.load(open('$session_file')).get('worktree_path', ''))" 2>/dev/null || echo "")
|
||||
local worktree_status=""
|
||||
if [ -n "$worktree_path" ]; then
|
||||
if [ -d "$worktree_path" ]; then
|
||||
worktree_status="(worktree exists)"
|
||||
else
|
||||
worktree_status="(worktree MISSING)"
|
||||
fi
|
||||
fi
|
||||
echo " $filename"
|
||||
echo " Issue: $issue_ref"
|
||||
echo " Session: $opencode_sid"
|
||||
echo " State: $state"
|
||||
echo " $worktree_status"
|
||||
fi
|
||||
fi
|
||||
done
|
||||
fi
|
||||
|
||||
if [ -d "$WORKTREES_DIR" ]; then
|
||||
echo ""
|
||||
echo "Worktrees without sessions:"
|
||||
for worktree in $(find "$WORKTREES_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null); do
|
||||
local worktree_name=$(basename "$worktree")
|
||||
local has_session=false
|
||||
for session_file in "$SESSIONS_DIR"/*.json; do
|
||||
if [ -f "$session_file" ]; then
|
||||
local wt_path=$(python3 -c "import json; print(json.load(open('$session_file')).get('worktree_path', ''))" 2>/dev/null || echo "")
|
||||
if [ "$wt_path" = "$worktree" ]; then
|
||||
has_session=true
|
||||
break
|
||||
fi
|
||||
fi
|
||||
done
|
||||
if [ "$has_session" = false ]; then
|
||||
echo " $worktree_name (no session)"
|
||||
fi
|
||||
done
|
||||
fi
|
||||
}
|
||||
|
||||
cmd_prune() {
|
||||
local force=false
|
||||
|
||||
if [ "$1" = "--force" ]; then
|
||||
force=true
|
||||
fi
|
||||
|
||||
echo "=== kugetsu prune ==="
|
||||
echo ""
|
||||
|
||||
local orphaned=()
|
||||
|
||||
if [ -d "$SESSIONS_DIR" ]; then
|
||||
for session_file in "$SESSIONS_DIR"/*.json; do
|
||||
[ -f "$session_file" ] || continue
|
||||
local filename=$(basename "$session_file")
|
||||
if [ "$filename" = "base.json" ] || [ "$filename" = "pm-agent.json" ]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
local opencode_sid=$(python3 -c "import json; print(json.load(open('$session_file')).get('opencode_session_id', ''))" 2>/dev/null || echo "")
|
||||
|
||||
if [ -n "$opencode_sid" ]; then
|
||||
local exists=$(opencode session list 2>/dev/null | grep -c "^$opencode_sid" || echo "0")
|
||||
if [ "$exists" -eq 0 ]; then
|
||||
orphaned+=("$session_file")
|
||||
fi
|
||||
else
|
||||
orphaned+=("$session_file")
|
||||
fi
|
||||
done
|
||||
fi
|
||||
|
||||
if [ ${#orphaned[@]} -eq 0 ]; then
|
||||
echo "No orphaned sessions found."
|
||||
return
|
||||
fi
|
||||
|
||||
echo "Found ${#orphaned[@]} orphaned session(s):"
|
||||
for session in "${orphaned[@]}"; do
|
||||
echo " $session"
|
||||
done
|
||||
echo ""
|
||||
|
||||
if [ "$force" = false ]; then
|
||||
read -p "Remove these sessions? [y/N] " -r answer
|
||||
if [[ ! "$answer" =~ ^[Yy]$ ]]; then
|
||||
echo "Aborted."
|
||||
return
|
||||
fi
|
||||
fi
|
||||
|
||||
for session in "${orphaned[@]}"; do
|
||||
local issue_ref=$(python3 -c "import json; print(json.load(open('$session')).get('issue_ref', ''))" 2>/dev/null || echo "")
|
||||
local worktree_path=$(python3 -c "import json; print(json.load(open('$session')).get('worktree_path', ''))" 2>/dev/null || echo "")
|
||||
|
||||
if [ -n "$worktree_path" ] && [ -d "$worktree_path" ]; then
|
||||
echo "Removing worktree: $worktree_path"
|
||||
git worktree remove "$worktree_path" 2>/dev/null || rm -rf "$worktree_path"
|
||||
fi
|
||||
|
||||
rm -f "$session"
|
||||
|
||||
if [ -n "$issue_ref" ]; then
|
||||
remove_issue_from_index "$issue_ref"
|
||||
fi
|
||||
|
||||
echo "Removed: $session"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "Pruned ${#orphaned[@]} orphaned session(s)."
|
||||
}
|
||||
|
||||
cmd_destroy() {
|
||||
local target="${1:-}"
|
||||
local force=false
|
||||
|
||||
if [ "${2:-}" = "-y" ]; then
|
||||
force=true
|
||||
fi
|
||||
|
||||
if [ -z "$target" ]; then
|
||||
echo "Error: target is required" >&2
|
||||
echo "Usage: kugetsu destroy <issue-ref> [-y]" >&2
|
||||
echo " kugetsu destroy --pm-agent [-y]" >&2
|
||||
echo " kugetsu destroy --base [-y]" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ "$target" = "--pm-agent" ]; then
|
||||
if [ "$force" = false ]; then
|
||||
echo "Warning: Destroying PM agent session is not recommended." >&2
|
||||
read -p "Continue? [y/N] " -r answer
|
||||
if [[ ! "$answer" =~ ^[Yy]$ ]]; then
|
||||
echo "Aborted."
|
||||
return
|
||||
fi
|
||||
fi
|
||||
|
||||
local pm_session=$(get_pm_agent_session_id)
|
||||
if [ -n "$pm_session" ] && [ "$pm_session" != "null" ]; then
|
||||
echo "Stopping PM agent session: $pm_session"
|
||||
opencode session stop "$pm_session" 2>/dev/null || true
|
||||
fi
|
||||
|
||||
rm -f "$SESSIONS_DIR/pm-agent.json"
|
||||
set_pm_agent_in_index "null"
|
||||
echo "PM agent session destroyed"
|
||||
elif [ "$target" = "--base" ]; then
|
||||
if [ "$force" = false ]; then
|
||||
echo "Warning: Destroying base session will remove ALL sessions." >&2
|
||||
read -p "Continue? [y/N] " -r answer
|
||||
if [[ ! "$answer" =~ ^[Yy]$ ]]; then
|
||||
echo "Aborted."
|
||||
return
|
||||
fi
|
||||
fi
|
||||
|
||||
for session_file in "$SESSIONS_DIR"/*.json; do
|
||||
[ -f "$session_file" ] || continue
|
||||
rm -f "$session_file"
|
||||
done
|
||||
|
||||
for worktree in "$WORKTREES_DIR"/.kugetsu-worktrees/*; do
|
||||
if [ -d "$worktree" ]; then
|
||||
git worktree remove "$worktree" 2>/dev/null || rm -rf "$worktree"
|
||||
fi
|
||||
done
|
||||
|
||||
write_index "null" "null" "{}"
|
||||
echo "Base session and all worktrees destroyed"
|
||||
else
|
||||
validate_issue_ref "$target"
|
||||
|
||||
local session_file=$(get_session_for_issue "$target")
|
||||
if [ -z "$session_file" ] || [ "$session_file" = "null" ]; then
|
||||
echo "Error: No session found for '$target'" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
local session_path="$SESSIONS_DIR/$session_file"
|
||||
|
||||
if [ "$force" = true ]; then
|
||||
remove_worktree_for_issue "$target"
|
||||
rm -f "$session_path"
|
||||
remove_issue_from_index "$target"
|
||||
echo "Session for '$target' destroyed"
|
||||
else
|
||||
echo "Warning: This will delete session and worktree for '$target'" >&2
|
||||
read -p "Continue? [y/N] " -r answer
|
||||
if [[ ! "$answer" =~ ^[Yy]$ ]]; then
|
||||
echo "Aborted."
|
||||
return
|
||||
fi
|
||||
|
||||
remove_worktree_for_issue "$target"
|
||||
rm -f "$session_path"
|
||||
remove_issue_from_index "$target"
|
||||
echo "Session for '$target' destroyed"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
cmd_status() {
|
||||
echo "=== kugetsu status ==="
|
||||
|
||||
local base_id=$(get_base_session_id)
|
||||
local pm_id=$(get_pm_agent_session_id)
|
||||
|
||||
if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
|
||||
echo "Status: Not initialized"
|
||||
echo "Run 'kugetsu init' to initialize."
|
||||
return
|
||||
fi
|
||||
|
||||
echo "Base session: $base_id"
|
||||
|
||||
if [ -n "$pm_id" ] && [ "$pm_id" != "null" ]; then
|
||||
echo "PM agent: $pm_id"
|
||||
else
|
||||
echo "PM agent: not running"
|
||||
fi
|
||||
|
||||
local active_count=$(count_active_dev_sessions)
|
||||
echo "Active issue sessions: $active_count / ${MAX_CONCURRENT_AGENTS:-3}"
|
||||
|
||||
echo ""
|
||||
echo "OpenCode sessions:"
|
||||
opencode session list 2>/dev/null || echo " (unable to list sessions)"
|
||||
}
|
||||
@@ -1,191 +0,0 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
issue_ref_to_worktree_name() {
|
||||
local issue_ref="$1"
|
||||
echo "$issue_ref" | sed 's/[\/:]/-/g' | sed 's/#/-/'
|
||||
}
|
||||
|
||||
issue_ref_to_worktree_path() {
|
||||
local issue_ref="$1"
|
||||
local parent_dir="${2:-$WORKTREES_DIR}"
|
||||
local worktree_name=$(issue_ref_to_worktree_name "$issue_ref")
|
||||
echo "$parent_dir/$worktree_name"
|
||||
}
|
||||
|
||||
issue_ref_to_branch_name() {
|
||||
local issue_ref="$1"
|
||||
local number_part=$(echo "$issue_ref" | grep -oE '#[0-9]+$' || echo "")
|
||||
if [ -n "$number_part" ]; then
|
||||
echo "fix/issue-${number_part#\#}"
|
||||
else
|
||||
local identifier=$(echo "$issue_ref" | grep -oE '#[^-]+$' || echo "")
|
||||
if [ -n "$identifier" ]; then
|
||||
local clean_id=$(echo "$identifier" | sed 's/^#//' | sed 's/-/_/g')
|
||||
echo "fix/${clean_id}"
|
||||
else
|
||||
echo "fix/issue-temp"
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
get_repo_url() {
|
||||
local issue_ref="$1"
|
||||
|
||||
if [ -f "$REPOS_CONFIG" ]; then
|
||||
local url=$(python3 -c "import json, sys; d=json.load(open('$REPOS_CONFIG')); print(d.get('$issue_ref', ''))" 2>/dev/null || echo "")
|
||||
if [ -n "$url" ]; then
|
||||
echo "$url"
|
||||
return
|
||||
fi
|
||||
fi
|
||||
|
||||
local instance=$(echo "$issue_ref" | cut -d'/' -f1 | cut -d'#' -f1)
|
||||
local rest=$(echo "$issue_ref" | sed 's/^[^\/]*\///' | sed 's/#.*//')
|
||||
|
||||
if [ -n "${GIT_SERVERS[$instance]:-}" ]; then
|
||||
echo "${GIT_SERVERS[$instance]}/${rest}.git"
|
||||
return
|
||||
fi
|
||||
|
||||
if [ -n "${GIT_SERVERS[$DEFAULT_GIT_SERVER]:-}" ]; then
|
||||
echo "${GIT_SERVERS[$DEFAULT_GIT_SERVER]}/${rest}.git"
|
||||
return
|
||||
fi
|
||||
|
||||
echo "https://${instance}/${rest}.git"
|
||||
}
|
||||
|
||||
worktree_exists() {
|
||||
local issue_ref="$1"
|
||||
local parent_dir="${2:-$PWD}"
|
||||
local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$parent_dir")
|
||||
[ -d "$worktree_path" ]
|
||||
}
|
||||
|
||||
create_worktree() {
|
||||
local issue_ref="$1"
|
||||
local parent_dir="${2:-$PWD}"
|
||||
local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$parent_dir")
|
||||
local branch_name=$(issue_ref_to_branch_name "$issue_ref")
|
||||
local repo_url=$(get_repo_url "$issue_ref")
|
||||
|
||||
if [ -z "$repo_url" ]; then
|
||||
echo "Error: Cannot determine repo URL for '$issue_ref'" >&2
|
||||
echo "Please add to $REPOS_CONFIG or ensure worktree exists" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
local worktree_parent_dir
|
||||
worktree_parent_dir=$(dirname "$worktree_path")
|
||||
mkdir -p "$worktree_parent_dir"
|
||||
|
||||
if worktree_exists "$issue_ref" "$parent_dir"; then
|
||||
echo "Removing existing worktree at '$worktree_path'..."
|
||||
git worktree remove "$worktree_path" 2>/dev/null || rm -rf "$worktree_path"
|
||||
fi
|
||||
|
||||
echo "Creating worktree at '$worktree_path'..."
|
||||
|
||||
local clone_success=false
|
||||
local attempt=0
|
||||
local max_attempts="${NETWORK_RETRY_ATTEMPTS:-3}"
|
||||
|
||||
while [ $attempt -lt $max_attempts ] && [ "$clone_success" = false ]; do
|
||||
attempt=$((attempt + 1))
|
||||
if [ $attempt -gt 1 ]; then
|
||||
echo "Clone attempt $attempt of $max_attempts..."
|
||||
sleep "$((attempt * 2))"
|
||||
fi
|
||||
|
||||
if git clone "$repo_url" "$worktree_path" 2>/dev/null; then
|
||||
clone_success=true
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "$clone_success" = false ]; then
|
||||
echo "Error: Failed to clone repository after $max_attempts attempts" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Creating branch '$branch_name'..."
|
||||
if git -C "$worktree_path" checkout -b "$branch_name" "$KUGETSU_BASE_BRANCH" 2>/dev/null; then
|
||||
:
|
||||
elif git -C "$worktree_path" checkout -b "$branch_name" main 2>/dev/null; then
|
||||
:
|
||||
else
|
||||
echo "Warning: Could not checkout branch (may need to run from within worktree after session)" >&2
|
||||
fi
|
||||
|
||||
echo "Worktree created at: $worktree_path"
|
||||
}
|
||||
|
||||
remove_worktree_for_issue() {
|
||||
local issue_ref="$1"
|
||||
local parent_dir="${2:-$PWD}"
|
||||
local worktree_path=$(issue_ref_to_worktree_path "$issue_ref" "$parent_dir")
|
||||
|
||||
if worktree_exists "$issue_ref" "$parent_dir"; then
|
||||
echo "Removing worktree at '$worktree_path'..."
|
||||
git worktree remove "$worktree_path" 2>/dev/null || rm -rf "$worktree_path"
|
||||
fi
|
||||
}
|
||||
|
||||
get_worktree_path_for_session() {
|
||||
local session_file="$1"
|
||||
if [ -f "$session_file" ]; then
|
||||
python3 -c "import json; print(json.load(open('$session_file')).get('worktree_path', ''))" 2>/dev/null || echo ""
|
||||
else
|
||||
echo ""
|
||||
fi
|
||||
}
|
||||
|
||||
check_pr_status() {
|
||||
local pr_url="$1"
|
||||
|
||||
if [ -z "$pr_url" ]; then
|
||||
echo "no_pr_url"
|
||||
return 1
|
||||
fi
|
||||
|
||||
local hostname=$(echo "$pr_url" | sed -E 's|https://([^/]+)/.*|\1|')
|
||||
|
||||
local server_base="${GIT_SERVERS[$hostname]:-}"
|
||||
if [ -z "$server_base" ]; then
|
||||
echo "unknown_server"
|
||||
return 1
|
||||
fi
|
||||
|
||||
local api_base="${server_base}/api/v1"
|
||||
|
||||
local api_url=$(echo "$pr_url" | sed -E 's|https://[^/]+/([^/]+)/([^/]+)/(pulls|merge_requests)/([0-9]+)|'"${api_base}"'/repos/\1/\2/\3/\4|')
|
||||
|
||||
local token=""
|
||||
if [[ "$hostname" == "github.com" ]]; then
|
||||
token="${GITHUB_TOKEN:-}"
|
||||
else
|
||||
token="${GITEA_TOKEN:-}"
|
||||
fi
|
||||
|
||||
local response_file="$KUGETSU_DIR/.pr_status_response_$$.json"
|
||||
if [ -n "$token" ]; then
|
||||
curl -s -H "Authorization: token $token" "$api_url" > "$response_file" 2>/dev/null || printf '{}' > "$response_file"
|
||||
else
|
||||
curl -s "$api_url" > "$response_file" 2>/dev/null || printf '{}' > "$response_file"
|
||||
fi
|
||||
|
||||
local state=$(python3 -c "import json; print(json.load(open('$response_file')).get('state', 'unknown'))" 2>/dev/null || echo "unknown")
|
||||
local merged=$(python3 -c "import json; print('true' if json.load(open('$response_file')).get('merged', False) else 'false')" 2>/dev/null || echo "false")
|
||||
|
||||
rm -f "$response_file"
|
||||
|
||||
if [ "$merged" = "true" ]; then
|
||||
echo "merged"
|
||||
elif [ "$state" = "closed" ]; then
|
||||
echo "closed"
|
||||
elif [ "$state" = "open" ]; then
|
||||
echo "open"
|
||||
else
|
||||
echo "unknown"
|
||||
fi
|
||||
}
|
||||
@@ -1,153 +0,0 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
USERNAME="${1:-kugetsu}"
|
||||
|
||||
echo "=== kugetsu SSH Setup ==="
|
||||
echo "Target user: $USERNAME"
|
||||
echo ""
|
||||
|
||||
detect_os() {
|
||||
if [ -f /etc/os-release ]; then
|
||||
. /etc/os-release
|
||||
case "$ID" in
|
||||
debian|ubuntu|"noble"|"jammy"|"focal"|"bionic"|"bullseye"|"bookworm"|"trixie"|"sid")
|
||||
echo "debian"
|
||||
;;
|
||||
fedora|rhel|centos|rocky|alma)
|
||||
echo "fedora"
|
||||
;;
|
||||
*)
|
||||
echo "unknown"
|
||||
;;
|
||||
esac
|
||||
else
|
||||
echo "unknown"
|
||||
fi
|
||||
}
|
||||
|
||||
OS_TYPE=$(detect_os)
|
||||
echo "Detected OS: $OS_TYPE"
|
||||
|
||||
if ! command -v systemctl &> /dev/null; then
|
||||
echo "ERROR: systemd not found."
|
||||
echo ""
|
||||
echo "This script requires systemd to be installed and running inside the container."
|
||||
echo "Please install systemd first:"
|
||||
case "$OS_TYPE" in
|
||||
debian)
|
||||
echo " apt-get update && apt-get install -y systemd"
|
||||
;;
|
||||
fedora)
|
||||
echo " dnf install -y systemd"
|
||||
;;
|
||||
*)
|
||||
echo " Install systemd using your package manager"
|
||||
;;
|
||||
esac
|
||||
echo ""
|
||||
echo "If you are running in a container that doesn't support systemd, consider:"
|
||||
echo " - Using a container image with systemd support"
|
||||
echo " - Running sshd directly (without systemd) - manual setup required"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== Step 1: Install openssh-server ==="
|
||||
case "$OS_TYPE" in
|
||||
debian)
|
||||
echo "Using apt-get (Debian/Ubuntu)..."
|
||||
apt-get update -qq
|
||||
apt-get install -y -qq openssh-server sudo
|
||||
;;
|
||||
fedora)
|
||||
echo "Using dnf (Fedora/RHEL)..."
|
||||
dnf install -y -q openssh-server sudo
|
||||
;;
|
||||
*)
|
||||
echo "ERROR: Unsupported OS. Please install openssh-server and sudo manually."
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
echo ""
|
||||
echo "=== Step 2: Verify installation ==="
|
||||
if ! command -v sshd &> /dev/null; then
|
||||
echo "ERROR: sshd installation failed."
|
||||
echo "Please verify openssh-server was installed correctly."
|
||||
exit 1
|
||||
fi
|
||||
echo "sshd binary: $(which sshd)"
|
||||
echo "sshd version: $(sshd -V 2>&1 | head -1)"
|
||||
|
||||
echo ""
|
||||
echo "=== Step 3: Create user '$USERNAME' ==="
|
||||
if ! id "$USERNAME" &> /dev/null; then
|
||||
useradd -m -s /bin/bash "$USERNAME"
|
||||
echo "User '$USERNAME' created."
|
||||
else
|
||||
echo "User '$USERNAME' already exists."
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== Step 4: Configure SSH for key-only authentication ==="
|
||||
SSHD_CONFIG="/etc/ssh/sshd_config"
|
||||
sed -i 's/^#*PasswordAuthentication.*/PasswordAuthentication no/' "$SSHD_CONFIG"
|
||||
sed -i 's/^#*PubkeyAuthentication.*/PubkeyAuthentication yes/' "$SSHD_CONFIG"
|
||||
sed -i 's/^#*PermitRootLogin.*/PermitRootLogin no/' "$SSHD_CONFIG"
|
||||
echo "SSH configured: key-only auth, root login disabled."
|
||||
|
||||
echo ""
|
||||
echo "=== Step 5: Configure sudo for passwordless access ==="
|
||||
SUDOERS_FILE="/etc/sudoers.d/$USERNAME"
|
||||
echo "$USERNAME ALL=(ALL) NOPASSWD: ALL" > "$SUDOERS_FILE"
|
||||
chmod 0440 "$SUDOERS_FILE"
|
||||
echo "Sudo configured: $USERNAME can run sudo without password."
|
||||
|
||||
echo ""
|
||||
echo "=== Step 6: Enable and start sshd ==="
|
||||
systemctl enable sshd
|
||||
systemctl restart sshd
|
||||
|
||||
sleep 1
|
||||
|
||||
echo ""
|
||||
echo "=== Step 7: Verify sshd is running ==="
|
||||
if systemctl is-active --quiet sshd; then
|
||||
echo "SUCCESS: sshd is running."
|
||||
echo "Status:"
|
||||
systemctl status sshd --no-pager | head -5
|
||||
else
|
||||
echo "ERROR: sshd is not running."
|
||||
echo "Debug info:"
|
||||
systemctl status sshd --no-pager
|
||||
journalctl -u sshd -n 10 --no-pager
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== Setup Complete ==="
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo ""
|
||||
echo "1. Add your SSH public key to authorized_keys:"
|
||||
echo " mkdir -p /home/$USERNAME/.ssh"
|
||||
echo " chmod 700 /home/$USERNAME/.ssh"
|
||||
echo " echo 'YOUR_PUBLIC_KEY' >> /home/$USERNAME/.ssh/authorized_keys"
|
||||
echo " chmod 600 /home/$USERNAME/.ssh/authorized_keys"
|
||||
echo " chown -R $USERNAME:$USERNAME /home/$USERNAME/.ssh"
|
||||
echo ""
|
||||
echo "2. Connect from remote:"
|
||||
echo " ssh -p 2222 $USERNAME@<container-host-ip>"
|
||||
echo ""
|
||||
echo "3. Verify SSH access:"
|
||||
echo " ssh -p 2222 $USERNAME@<container-host-ip> sudo systemctl status sshd"
|
||||
echo ""
|
||||
echo "=== Troubleshooting ==="
|
||||
echo ""
|
||||
echo "If SSH connection fails:"
|
||||
echo " - Check sshd is running: systemctl status sshd"
|
||||
echo " - Check sshd logs: journalctl -u sshd -n 20"
|
||||
echo " - Verify user exists: id $USERNAME"
|
||||
echo " - Verify SSH key was added: cat /home/$USERNAME/.ssh/authorized_keys"
|
||||
echo ""
|
||||
@@ -1,168 +0,0 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
USERNAME="${1:-$(whoami)}"
|
||||
HOSTNAME="${2:-$(hostname)}"
|
||||
|
||||
echo "=== kugetsu Tailscale Setup ==="
|
||||
echo "Target user: $USERNAME"
|
||||
echo "Device name: $HOSTNAME"
|
||||
echo ""
|
||||
|
||||
detect_os() {
|
||||
if [ -f /etc/os-release ]; then
|
||||
. /etc/os-release
|
||||
case "$ID" in
|
||||
debian|ubuntu|"noble"|"jammy"|"focal"|"bionic"|"bullseye"|"bookworm"|"trixie"|"sid")
|
||||
echo "debian"
|
||||
;;
|
||||
fedora|rhel|centos|rocky|alma)
|
||||
echo "fedora"
|
||||
;;
|
||||
*)
|
||||
echo "unknown"
|
||||
;;
|
||||
esac
|
||||
else
|
||||
echo "unknown"
|
||||
fi
|
||||
}
|
||||
|
||||
OS_TYPE=$(detect_os)
|
||||
echo "Detected OS: $OS_TYPE"
|
||||
|
||||
echo ""
|
||||
echo "=== Step 1: Installing Tailscale ==="
|
||||
|
||||
install_tailscale() {
|
||||
case "$OS_TYPE" in
|
||||
debian)
|
||||
echo "Installing Tailscale via apt (Debian/Ubuntu)..."
|
||||
curl -fsSL https://tailscale.com/install.sh | sh
|
||||
;;
|
||||
fedora)
|
||||
echo "Installing Tailscale via dnf (Fedora/RHEL)..."
|
||||
# Create repo file manually (gpgcheck=0 since the GPG key URL may return 404)
|
||||
echo "[tailscale]
|
||||
name=Tailscale
|
||||
baseurl=https://pkgs.tailscale.com/stable/fedora/x86_64
|
||||
enabled=1
|
||||
gpgcheck=0" | sudo tee /etc/yum.repos.d/tailscale.repo > /dev/null
|
||||
sudo dnf install -y tailscale
|
||||
;;
|
||||
*)
|
||||
echo "ERROR: Unsupported OS. Please install Tailscale manually."
|
||||
echo "See: https://tailscale.com/download"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
if command -v tailscale &> /dev/null; then
|
||||
echo "Tailscale is already installed: $(tailscale --version)"
|
||||
else
|
||||
install_tailscale
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== Step 2: Verify Tailscale installation ==="
|
||||
if ! command -v tailscale &> /dev/null; then
|
||||
echo "ERROR: Tailscale installation failed."
|
||||
exit 1
|
||||
fi
|
||||
echo "Tailscale binary: $(which tailscale)"
|
||||
echo "Tailscale version: $(tailscale --version)"
|
||||
|
||||
echo ""
|
||||
echo "=== Step 3: Start tailscaled daemon ==="
|
||||
systemctl enable --now tailscaled
|
||||
sleep 2
|
||||
|
||||
if systemctl is-active --quiet tailscaled; then
|
||||
echo "SUCCESS: tailscaled is running."
|
||||
else
|
||||
echo "ERROR: tailscaled failed to start."
|
||||
echo "Debug: systemctl status tailscaled"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== Step 4: Authentication ==="
|
||||
|
||||
auth_method() {
|
||||
echo "Choose authentication method:"
|
||||
echo " 1) AUTHKEY - Use a pre-generated auth key (headless/scripted)"
|
||||
echo " 2) Headless - Get a login URL to click in browser"
|
||||
echo ""
|
||||
read -p "Enter choice [1/2]: " choice
|
||||
|
||||
case "$choice" in
|
||||
1)
|
||||
echo ""
|
||||
echo "To generate an AUTHKEY:"
|
||||
echo " 1. Go to: https://login.tailscale.com/admin/settings/keys"
|
||||
echo " 2. Click 'Generate auth key'"
|
||||
echo " 3. Copy the key (starts with 'tskey-auth-')"
|
||||
echo ""
|
||||
read -p "Paste your AUTHKEY (or press Enter to cancel): " AUTHKEY
|
||||
|
||||
if [ -z "$AUTHKEY" ]; then
|
||||
echo "Cancelled."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [[ ! "$AUTHKEY" =~ ^tskey-auth ]]; then
|
||||
echo "ERROR: AUTHKEY should start with 'tskey-auth-'. Please check and try again."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "Connecting with AUTHKEY..."
|
||||
tailscale up --authkey="$AUTHKEY" --hostname="$HOSTNAME" --operator="$USERNAME"
|
||||
;;
|
||||
2|"")
|
||||
echo ""
|
||||
echo "Getting login URL..."
|
||||
echo "After you click the URL and authenticate in browser, this script will continue."
|
||||
echo ""
|
||||
tailscale up --hostname="$HOSTNAME" --operator="$USERNAME"
|
||||
;;
|
||||
*)
|
||||
echo "Invalid choice. Please enter 1 or 2."
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
auth_method
|
||||
|
||||
echo ""
|
||||
echo "=== Step 5: Verify Tailscale connection ==="
|
||||
sleep 2
|
||||
|
||||
if tailscale status &> /dev/null; then
|
||||
echo "SUCCESS: Connected to Tailscale!"
|
||||
echo ""
|
||||
echo "Your Tailscale IP:"
|
||||
tailscale ip -4
|
||||
echo ""
|
||||
echo "Your Tailscale hostname: $HOSTNAME"
|
||||
echo ""
|
||||
echo "To connect from another Tailscale device:"
|
||||
echo " ssh $USERNAME@$HOSTNAME"
|
||||
echo ""
|
||||
echo "Or directly via IP:"
|
||||
echo " ssh $USERNAME@$(tailscale ip -4)"
|
||||
else
|
||||
echo "WARNING: Tailscale may not be fully connected yet."
|
||||
echo "Check status with: tailscale status"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== Setup Complete ==="
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo " - Install Tailscale on your other devices: https://tailscale.com/download"
|
||||
echo " - Add this device to your tailnet"
|
||||
echo " - SSH from anywhere using: ssh $USERNAME@$HOSTNAME"
|
||||
echo ""
|
||||
@@ -1,181 +0,0 @@
|
||||
#!/bin/bash
|
||||
# Tests for create_session function
|
||||
#
|
||||
# Run with: bash skills/kugetsu/tests/test-create-session.sh
|
||||
#
|
||||
# NOTE: These tests MUST be run sequentially (not in parallel)
|
||||
# to avoid exhausting memory with too many opencode sessions.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
source "$SCRIPT_DIR/../scripts/kugetsu-config.sh"
|
||||
source "$SCRIPT_DIR/../scripts/kugetsu-index.sh"
|
||||
source "$SCRIPT_DIR/../scripts/kugetsu-session.sh"
|
||||
|
||||
PASS=0
|
||||
FAIL=0
|
||||
RUN=0
|
||||
|
||||
pass() {
|
||||
echo "PASS: $1"
|
||||
PASS=$((PASS + 1))
|
||||
}
|
||||
|
||||
fail() {
|
||||
echo "FAIL: $1"
|
||||
echo " Expected: $2"
|
||||
echo " Got: $3"
|
||||
FAIL=$((FAIL + 1))
|
||||
}
|
||||
|
||||
run_test() {
|
||||
local name="$1"
|
||||
local test_func="$2"
|
||||
RUN=$((RUN + 1))
|
||||
echo ""
|
||||
echo "=== Test $RUN: $name ==="
|
||||
echo "--- $name ---"
|
||||
$test_func
|
||||
}
|
||||
|
||||
echo "=== create_session Test Suite ==="
|
||||
echo "NOTE: Running sequentially to avoid memory exhaustion"
|
||||
echo ""
|
||||
|
||||
# Test 1: create_session requires base session
|
||||
test_create_session_requires_base() {
|
||||
local base_id=$(get_base_session_id)
|
||||
if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
|
||||
skip "Base session not initialized - run 'kugetsu init' first"
|
||||
return
|
||||
fi
|
||||
|
||||
local result=$(create_session "$base_id")
|
||||
if [ -n "$result" ] && [[ "$result" =~ ^ses_ ]]; then
|
||||
pass "create_session returns valid session ID"
|
||||
else
|
||||
fail "create_session returns valid session ID" "ses_xxx" "$result"
|
||||
fi
|
||||
}
|
||||
|
||||
# Test 2: create_session creates a NEW session (different from base)
|
||||
test_create_session_is_new() {
|
||||
local base_id=$(get_base_session_id)
|
||||
if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
|
||||
skip "Base session not initialized - run 'kugetsu init' first"
|
||||
return
|
||||
fi
|
||||
|
||||
local new_id=$(create_session "$base_id")
|
||||
if [ "$new_id" != "$base_id" ]; then
|
||||
pass "create_session returns NEW session (not same as base)"
|
||||
else
|
||||
fail "create_session returns NEW session" "different from base_id" "$new_id"
|
||||
fi
|
||||
}
|
||||
|
||||
# Test 3: create_session can be called multiple times (creates different sessions)
|
||||
test_create_session_multiple_calls() {
|
||||
local base_id=$(get_base_session_id)
|
||||
if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
|
||||
skip "Base session not initialized - run 'kugetsu init' first"
|
||||
return
|
||||
fi
|
||||
|
||||
local id1=$(create_session "$base_id")
|
||||
sleep 1
|
||||
local id2=$(create_session "$base_id")
|
||||
|
||||
if [ "$id1" != "$id2" ]; then
|
||||
pass "create_session creates different sessions on each call"
|
||||
else
|
||||
fail "create_session creates different sessions" "$id1 != $id2" "both equal: $id1"
|
||||
fi
|
||||
}
|
||||
|
||||
# Test 4: JSON session list parsing
|
||||
test_session_json_parsing() {
|
||||
local json='[{"id": "ses_abc123", "title": "test"}, {"id": "ses_def456", "title": "test2"}]'
|
||||
local ids=$(echo "$json" | python3 -c "import sys,json; sessions=json.load(sys.stdin); print(' '.join(s['id'] for s in sessions))" 2>/dev/null)
|
||||
|
||||
if [ "$ids" = "ses_abc123 ses_def456" ]; then
|
||||
pass "JSON session list parsing extracts IDs correctly"
|
||||
else
|
||||
fail "JSON session list parsing" "ses_abc123 ses_def456" "$ids"
|
||||
fi
|
||||
}
|
||||
|
||||
# Test 5: Session ID format validation
|
||||
test_session_id_format() {
|
||||
local json='[{"id": "ses_2b4814406ffe3AxcpbrP7FknDr", "title": "test"}]'
|
||||
local ids=$(echo "$json" | python3 -c "import sys,json; sessions=json.load(sys.stdin); print(' '.join(s['id'] for s in sessions))" 2>/dev/null)
|
||||
|
||||
if [[ "$ids" =~ ^ses_ ]]; then
|
||||
pass "Session ID format is valid (starts with ses_)"
|
||||
else
|
||||
fail "Session ID format" "ses_xxx" "$ids"
|
||||
fi
|
||||
}
|
||||
|
||||
# Test 6: create_session accepts optional base session parameter
|
||||
test_create_session_with_param() {
|
||||
local base_id=$(get_base_session_id)
|
||||
if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
|
||||
skip "Base session not initialized - run 'kugetsu init' first"
|
||||
return
|
||||
fi
|
||||
|
||||
local result=$(create_session "$base_id")
|
||||
if [ -n "$result" ] && [[ "$result" =~ ^ses_ ]]; then
|
||||
pass "create_session accepts base session parameter"
|
||||
else
|
||||
fail "create_session accepts base session parameter" "ses_xxx" "$result"
|
||||
fi
|
||||
}
|
||||
|
||||
# Test 7: Verify session appears in opencode session list after creation
|
||||
test_session_visible_in_list() {
|
||||
local base_id=$(get_base_session_id)
|
||||
if [ -z "$base_id" ] || [ "$base_id" = "null" ]; then
|
||||
skip "Base session not initialized - run 'kugetsu init' first"
|
||||
return
|
||||
fi
|
||||
|
||||
local new_id=$(create_session "$base_id")
|
||||
sleep 1
|
||||
|
||||
local all_sessions=$(opencode session list --format=json 2>/dev/null)
|
||||
if echo "$all_sessions" | grep -q "$new_id"; then
|
||||
pass "Created session appears in opencode session list"
|
||||
else
|
||||
fail "Created session appears in session list" "should contain $new_id" "$all_sessions"
|
||||
fi
|
||||
}
|
||||
|
||||
skip() {
|
||||
echo "SKIP: $1"
|
||||
}
|
||||
|
||||
# Run tests sequentially
|
||||
run_test "create_session requires base session" test_create_session_requires_base
|
||||
run_test "create_session creates NEW session" test_create_session_is_new
|
||||
run_test "create_session creates different sessions on multiple calls" test_create_session_multiple_calls
|
||||
run_test "JSON session list parsing" test_session_json_parsing
|
||||
run_test "Session ID format validation" test_session_id_format
|
||||
run_test "create_session accepts optional base session parameter" test_create_session_with_param
|
||||
run_test "Created session visible in opencode session list" test_session_visible_in_list
|
||||
|
||||
echo ""
|
||||
echo "=== Test Results ==="
|
||||
echo "Passed: $PASS"
|
||||
echo "Failed: $FAIL"
|
||||
echo "Total: $RUN"
|
||||
|
||||
if [ $FAIL -eq 0 ]; then
|
||||
echo "All tests passed!"
|
||||
exit 0
|
||||
else
|
||||
echo "Some tests failed!"
|
||||
exit 1
|
||||
fi
|
||||
@@ -1,298 +0,0 @@
|
||||
#!/bin/bash
|
||||
# Git URL Parsing Tests for kugetsu
|
||||
# Tests all functions that parse or construct git URLs and issue refs
|
||||
#
|
||||
# Run with: bash skills/kugetsu/tests/test-git-url-parsing.sh
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
source "$SCRIPT_DIR/../scripts/kugetsu-config.sh"
|
||||
source "$SCRIPT_DIR/../scripts/kugetsu-worktree.sh"
|
||||
source "$SCRIPT_DIR/../scripts/kugetsu-session.sh"
|
||||
|
||||
PASS=0
|
||||
FAIL=0
|
||||
|
||||
pass() {
|
||||
echo "PASS: $1"
|
||||
PASS=$((PASS + 1))
|
||||
}
|
||||
|
||||
fail() {
|
||||
echo "FAIL: $1"
|
||||
echo " Expected: $2"
|
||||
echo " Got: $3"
|
||||
FAIL=$((FAIL + 1))
|
||||
}
|
||||
|
||||
echo "=== Git URL Parsing Test Suite ==="
|
||||
echo ""
|
||||
|
||||
# Test: get_repo_url with standard GitHub issue ref
|
||||
echo "--- Test: get_repo_url with github.com ---"
|
||||
result=$(get_repo_url "github.com/shoko/kugetsu#14")
|
||||
expected="https://github.com/shoko/kugetsu.git"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "get_repo_url standard github issue ref"
|
||||
else
|
||||
fail "get_repo_url standard github issue ref" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: get_repo_url with custom instance
|
||||
echo "--- Test: get_repo_url with git.fbrns.co ---"
|
||||
result=$(get_repo_url "git.fbrns.co/shoko/kugetsu#158")
|
||||
expected="https://git.fbrns.co/shoko/kugetsu.git"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "get_repo_url custom instance issue ref (ISSUE #181)"
|
||||
else
|
||||
fail "get_repo_url custom instance issue ref (ISSUE #181)" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: get_repo_url with gitlab.com (if configured)
|
||||
echo "--- Test: get_repo_url with gitlab.com ---"
|
||||
if [ -n "${GIT_SERVERS[gitlab.com]:-}" ]; then
|
||||
result=$(get_repo_url "gitlab.com/someuser/somerepo#42")
|
||||
expected="https://gitlab.com/someuser/somerepo.git"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "get_repo_url gitlab.com issue ref"
|
||||
else
|
||||
fail "get_repo_url gitlab.com issue ref" "$expected" "$result"
|
||||
fi
|
||||
else
|
||||
echo "SKIP: get_repo_url gitlab.com (not configured in GIT_SERVERS)"
|
||||
fi
|
||||
|
||||
# Test: get_repo_url with bitbucket.org (if configured)
|
||||
echo "--- Test: get_repo_url with bitbucket.org ---"
|
||||
if [ -n "${GIT_SERVERS[bitbucket.org]:-}" ]; then
|
||||
result=$(get_repo_url "bitbucket.org/myteam/myproject#7")
|
||||
expected="https://bitbucket.org/myteam/myproject.git"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "get_repo_url bitbucket.org issue ref"
|
||||
else
|
||||
fail "get_repo_url bitbucket.org issue ref" "$expected" "$result"
|
||||
fi
|
||||
else
|
||||
echo "SKIP: get_repo_url bitbucket.org (not configured in GIT_SERVERS)"
|
||||
fi
|
||||
|
||||
# Test: get_repo_url with large issue number
|
||||
echo "--- Test: get_repo_url with large issue number ---"
|
||||
result=$(get_repo_url "github.com/shoko/kugetsu#999999")
|
||||
expected="https://github.com/shoko/kugetsu.git"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "get_repo_url with large issue number"
|
||||
else
|
||||
fail "get_repo_url with large issue number" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: issue_ref_to_worktree_name standard
|
||||
echo "--- Test: issue_ref_to_worktree_name standard ---"
|
||||
result=$(issue_ref_to_worktree_name "github.com/shoko/kugetsu#14")
|
||||
expected="github.com-shoko-kugetsu-14"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "issue_ref_to_worktree_name standard"
|
||||
else
|
||||
fail "issue_ref_to_worktree_name standard" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: issue_ref_to_worktree_name with custom instance
|
||||
echo "--- Test: issue_ref_to_worktree_name custom instance ---"
|
||||
result=$(issue_ref_to_worktree_name "git.fbrns.co/shoko/kugetsu#158")
|
||||
expected="git.fbrns.co-shoko-kugetsu-158"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "issue_ref_to_worktree_name custom instance"
|
||||
else
|
||||
fail "issue_ref_to_worktree_name custom instance" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: issue_ref_to_branch_name with number
|
||||
echo "--- Test: issue_ref_to_branch_name with number ---"
|
||||
result=$(issue_ref_to_branch_name "github.com/shoko/kugetsu#14")
|
||||
expected="fix/issue-14"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "issue_ref_to_branch_name with number"
|
||||
else
|
||||
fail "issue_ref_to_branch_name with number" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: issue_ref_to_branch_name with discuss suffix
|
||||
# Note: #-discuss falls through to fix/issue-temp because #[^-]+$ doesn't match #-<text-with-hyphens>
|
||||
echo "--- Test: issue_ref_to_branch_name with discuss suffix ---"
|
||||
result=$(issue_ref_to_branch_name "github.com/shoko/kugetsu#-discuss")
|
||||
expected="fix/issue-temp"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "issue_ref_to_branch_name with discuss suffix"
|
||||
else
|
||||
fail "issue_ref_to_branch_name with discuss suffix" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: issue_ref_to_branch_name with identifier that has no hyphens
|
||||
echo "--- Test: issue_ref_to_branch_name with pure identifier ---"
|
||||
result=$(issue_ref_to_branch_name "github.com/shoko/kugetsu#someid")
|
||||
expected="fix/someid"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "issue_ref_to_branch_name with pure identifier"
|
||||
else
|
||||
fail "issue_ref_to_branch_name with pure identifier" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: issue_ref_to_branch_name without number
|
||||
echo "--- Test: issue_ref_to_branch_name without number ---"
|
||||
result=$(issue_ref_to_branch_name "github.com/shoko/kugetsu#abc")
|
||||
expected="fix/abc"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "issue_ref_to_branch_name without number"
|
||||
else
|
||||
fail "issue_ref_to_branch_name without number" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: extract_issue_ref_from_message with short form
|
||||
echo "--- Test: extract_issue_ref_from_message short form ---"
|
||||
result=$(extract_issue_ref_from_message "github.com/shoko/kugetsu#14")
|
||||
expected="github.com/shoko/kugetsu#14"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "extract_issue_ref_from_message short form"
|
||||
else
|
||||
fail "extract_issue_ref_from_message short form" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: extract_issue_ref_from_message with https URL
|
||||
echo "--- Test: extract_issue_ref_from_message with https URL ---"
|
||||
result=$(extract_issue_ref_from_message "https://github.com/shoko/kugetsu/issues/14")
|
||||
expected="github.com/shoko/kugetsu#14"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "extract_issue_ref_from_message with https URL"
|
||||
else
|
||||
fail "extract_issue_ref_from_message with https URL" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: extract_issue_ref_from_message with custom instance
|
||||
echo "--- Test: extract_issue_ref_from_message custom instance ---"
|
||||
result=$(extract_issue_ref_from_message "https://git.fbrns.co/shoko/kugetsu/issues/158")
|
||||
expected="git.fbrns.co/shoko/kugetsu#158"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "extract_issue_ref_from_message custom instance"
|
||||
else
|
||||
fail "extract_issue_ref_from_message custom instance" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: extract_issue_ref_from_message with empty message
|
||||
echo "--- Test: extract_issue_ref_from_message empty message ---"
|
||||
result=$(extract_issue_ref_from_message "")
|
||||
expected=""
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "extract_issue_ref_from_message empty message"
|
||||
else
|
||||
fail "extract_issue_ref_from_message empty message" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: extract_issue_ref_from_message with no issue ref
|
||||
echo "--- Test: extract_issue_ref_from_message no issue ref ---"
|
||||
result=$(extract_issue_ref_from_message "Just a regular message without any issue reference")
|
||||
expected=""
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "extract_issue_ref_from_message no issue ref"
|
||||
else
|
||||
fail "extract_issue_ref_from_message no issue ref" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: extract_issue_ref_from_message with gitlab URL
|
||||
echo "--- Test: extract_issue_ref_from_message gitlab URL ---"
|
||||
result=$(extract_issue_ref_from_message "https://gitlab.com/someuser/somerepo/issues/42")
|
||||
expected="gitlab.com/someuser/somerepo#42"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "extract_issue_ref_from_message gitlab URL"
|
||||
else
|
||||
fail "extract_issue_ref_from_message gitlab URL" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: validate_issue_ref valid format
|
||||
echo "--- Test: validate_issue_ref valid format ---"
|
||||
if validate_issue_ref "github.com/shoko/kugetsu#14" 2>/dev/null; then
|
||||
pass "validate_issue_ref valid format"
|
||||
else
|
||||
fail "validate_issue_ref valid format" "exit 0" "exit non-zero"
|
||||
fi
|
||||
|
||||
# Test: validate_issue_ref invalid format (missing parts)
|
||||
echo "--- Test: validate_issue_ref invalid format ---"
|
||||
if ! validate_issue_ref "invalid-ref" 2>/dev/null; then
|
||||
pass "validate_issue_ref invalid format"
|
||||
else
|
||||
fail "validate_issue_ref invalid format" "exit non-zero" "exit 0"
|
||||
fi
|
||||
|
||||
# Test: issue_ref_to_filename
|
||||
echo "--- Test: issue_ref_to_filename ---"
|
||||
result=$(issue_ref_to_filename "github.com/shoko/kugetsu#14")
|
||||
expected="github.com-shoko-kugetsu-14.json"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "issue_ref_to_filename"
|
||||
else
|
||||
fail "issue_ref_to_filename" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: filename_to_issue_ref
|
||||
echo "--- Test: filename_to_issue_ref ---"
|
||||
result=$(filename_to_issue_ref "github.com-shoko-kugetsu-14.json")
|
||||
expected="github.com/shoko/kugetsu#14"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "filename_to_issue_ref"
|
||||
else
|
||||
fail "filename_to_issue_ref" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: get_repo_url with org having hyphen
|
||||
echo "--- Test: get_repo_url with hyphenated org ---"
|
||||
result=$(get_repo_url "github.com/my-org/my-repo#1")
|
||||
expected="https://github.com/my-org/my-repo.git"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "get_repo_url with hyphenated org"
|
||||
else
|
||||
fail "get_repo_url with hyphenated org" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: get_repo_url with repo having dots
|
||||
echo "--- Test: get_repo_url with dotted repo ---"
|
||||
result=$(get_repo_url "github.com/shoko/kugetsu.utils#5")
|
||||
expected="https://github.com/shoko/kugetsu.utils.git"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "get_repo_url with dotted repo"
|
||||
else
|
||||
fail "get_repo_url with dotted repo" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: get_repo_url with underscore in username
|
||||
echo "--- Test: get_repo_url with underscore in user ---"
|
||||
result=$(get_repo_url "github.com/my_user/my_repo#10")
|
||||
expected="https://github.com/my_user/my_repo.git"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "get_repo_url with underscore in user"
|
||||
else
|
||||
fail "get_repo_url with underscore in user" "$expected" "$result"
|
||||
fi
|
||||
|
||||
# Test: get_repo_url with instance not in GIT_SERVERS (fallback)
|
||||
echo "--- Test: get_repo_url with unknown instance ---"
|
||||
result=$(get_repo_url "unknown.example.com/owner/repo#1")
|
||||
expected="https://unknown.example.com/owner/repo.git"
|
||||
if [ "$result" = "$expected" ]; then
|
||||
pass "get_repo_url with unknown instance"
|
||||
else
|
||||
fail "get_repo_url with unknown instance" "$expected" "$result"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== Test Results ==="
|
||||
echo "Passed: $PASS"
|
||||
echo "Failed: $FAIL"
|
||||
|
||||
if [ $FAIL -eq 0 ]; then
|
||||
echo "All tests passed!"
|
||||
exit 0
|
||||
else
|
||||
echo "Some tests failed!"
|
||||
exit 1
|
||||
fi
|
||||
@@ -1,855 +0,0 @@
|
||||
#!/bin/bash
|
||||
# kugetsu v2.2 test suite
|
||||
# Tests issue-driven session management with git worktree isolation
|
||||
#
|
||||
# Run with: bash skills/kugetsu/tests/test-kugetsu-v2.sh
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
KUGETSU="./skills/kugetsu/scripts/kugetsu"
|
||||
TEST_KUGETSU_DIR="/tmp/test-kugetsu-$$"
|
||||
export KUGETSU_DIR="$TEST_KUGETSU_DIR"
|
||||
TEST_ISSUE_REF="github.com/shoko/kugetsu#14"
|
||||
TEST_DISCUSS_REF="github.com/shoko/kugetsu#-discuss"
|
||||
TEST_BASE_SESSION_ID="ses_test_base_123"
|
||||
TEST_PM_AGENT_SESSION_ID="ses_test_pm_456"
|
||||
TEST_BASE_SESSION_FILE="base.json"
|
||||
TEST_PM_AGENT_SESSION_FILE="pm-agent.json"
|
||||
TEST_FORKED_SESSION_FILE="github.com-shoko-kugetsu-14.json"
|
||||
PASS=0
|
||||
FAIL=0
|
||||
|
||||
cleanup() {
|
||||
rm -rf "$TEST_KUGETSU_DIR" 2>/dev/null || true
|
||||
}
|
||||
|
||||
setup_mock_base() {
|
||||
mkdir -p "$TEST_KUGETSU_DIR/sessions" "$TEST_KUGETSU_DIR/worktrees"
|
||||
cat > "$TEST_KUGETSU_DIR/index.json" << EOF
|
||||
{
|
||||
"base": "$TEST_BASE_SESSION_ID",
|
||||
"pm_agent": "$TEST_PM_AGENT_SESSION_ID",
|
||||
"issues": {}
|
||||
}
|
||||
EOF
|
||||
cat > "$TEST_KUGETSU_DIR/sessions/$TEST_BASE_SESSION_FILE" << EOF
|
||||
{"type": "base", "opencode_session_id": "$TEST_BASE_SESSION_ID", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}
|
||||
EOF
|
||||
cat > "$TEST_KUGETSU_DIR/sessions/$TEST_PM_AGENT_SESSION_FILE" << EOF
|
||||
{"type": "pm_agent", "opencode_session_id": "$TEST_PM_AGENT_SESSION_ID", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}
|
||||
EOF
|
||||
}
|
||||
|
||||
setup_mock_forked() {
|
||||
cat > "$TEST_KUGETSU_DIR/index.json" << EOF
|
||||
{
|
||||
"base": "$TEST_BASE_SESSION_ID",
|
||||
"pm_agent": "$TEST_PM_AGENT_SESSION_ID",
|
||||
"issues": {
|
||||
"$TEST_ISSUE_REF": "$TEST_FORKED_SESSION_FILE"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
cat > "$TEST_KUGETSU_DIR/sessions/$TEST_FORKED_SESSION_FILE" << EOF
|
||||
{"type": "forked", "issue_ref": "$TEST_ISSUE_REF", "opencode_session_id": "ses_forked_789", "worktree_path": "/tmp/test-worktree", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}
|
||||
EOF
|
||||
}
|
||||
|
||||
pass() {
|
||||
echo "PASS: $1"
|
||||
PASS=$((PASS + 1))
|
||||
}
|
||||
|
||||
fail() {
|
||||
echo "FAIL: $1"
|
||||
FAIL=$((FAIL + 1))
|
||||
}
|
||||
|
||||
cleanup
|
||||
|
||||
echo "=== kugetsu v2.0 Test Suite ==="
|
||||
echo ""
|
||||
|
||||
# Test 1: Help shows new commands
|
||||
echo "--- Test: help ---"
|
||||
OUTPUT=$($KUGETSU help 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "kugetsu init"; then
|
||||
pass "help shows kugetsu init"
|
||||
else
|
||||
fail "help shows kugetsu init"
|
||||
fi
|
||||
|
||||
if echo "$OUTPUT" | grep -q "kugetsu continue"; then
|
||||
pass "help shows kugetsu continue"
|
||||
else
|
||||
fail "help shows kugetsu continue"
|
||||
fi
|
||||
|
||||
if echo "$OUTPUT" | grep -q "kugetsu prune"; then
|
||||
pass "help shows kugetsu prune"
|
||||
else
|
||||
fail "help shows kugetsu prune"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 2: init fails without TTY
|
||||
echo "--- Test: init without TTY ---"
|
||||
OUTPUT=$($KUGETSU init 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "requires a terminal"; then
|
||||
pass "init fails gracefully without TTY"
|
||||
else
|
||||
fail "init fails gracefully without TTY: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 3: start fails without base session
|
||||
echo "--- Test: start without base session ---"
|
||||
OUTPUT=$($KUGETSU start github.com/shoko/kugetsu#14 "test" 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "No base session"; then
|
||||
pass "start fails without base session"
|
||||
else
|
||||
fail "start fails without base session: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 3b: start fails without pm-agent
|
||||
echo "--- Test: start without pm-agent session ---"
|
||||
rm -f $TEST_KUGETSU_DIR/index.json $TEST_KUGETSU_DIR/sessions/*
|
||||
mkdir -p $TEST_KUGETSU_DIR/sessions
|
||||
cat > $TEST_KUGETSU_DIR/index.json << EOF
|
||||
{
|
||||
"base": "$TEST_BASE_SESSION_ID",
|
||||
"pm_agent": null,
|
||||
"issues": {}
|
||||
}
|
||||
EOF
|
||||
cat > $TEST_KUGETSU_DIR/sessions/$TEST_BASE_SESSION_FILE << EOF
|
||||
{"type": "base", "opencode_session_id": "$TEST_BASE_SESSION_ID", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}
|
||||
EOF
|
||||
OUTPUT=$($KUGETSU start github.com/shoko/kugetsu#14 "test" 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "No PM agent"; then
|
||||
pass "start fails without pm-agent session"
|
||||
else
|
||||
fail "start fails without pm-agent: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 4: start fails with invalid issue ref
|
||||
echo "--- Test: start with invalid issue ref ---"
|
||||
OUTPUT=$($KUGETSU start "invalid-ref" "test" 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "invalid issue ref"; then
|
||||
pass "start validates issue ref format"
|
||||
else
|
||||
fail "start validates issue ref format: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 5: list with no sessions
|
||||
echo "--- Test: list (empty) ---"
|
||||
cleanup
|
||||
OUTPUT=$($KUGETSU list 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "ISSUE_REF"; then
|
||||
pass "list shows header"
|
||||
else
|
||||
fail "list shows header: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 6: list with base session
|
||||
echo "--- Test: list with base session ---"
|
||||
setup_mock_base
|
||||
OUTPUT=$($KUGETSU list 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "base"; then
|
||||
pass "list shows base session"
|
||||
else
|
||||
fail "list shows base session: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 6b: list shows pm-agent
|
||||
echo "--- Test: list with pm-agent session ---"
|
||||
OUTPUT=$($KUGETSU list 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "pm-agent"; then
|
||||
pass "list shows pm-agent session"
|
||||
else
|
||||
fail "list shows pm-agent session: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 6c: index.json has pm_agent field
|
||||
echo "--- Test: index.json has pm_agent field ---"
|
||||
if grep -q '"pm_agent"' $TEST_KUGETSU_DIR/index.json; then
|
||||
pass "index.json has pm_agent field"
|
||||
else
|
||||
fail "index.json missing pm_agent field"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 7: continue fails without session
|
||||
echo "--- Test: continue without session ---"
|
||||
OUTPUT=$($KUGETSU continue github.com/shoko/kugetsu#999 "test" 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "No session found"; then
|
||||
pass "continue fails without session"
|
||||
else
|
||||
fail "continue fails without session: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 8: destroy without args fails
|
||||
echo "--- Test: destroy without args ---"
|
||||
OUTPUT=$($KUGETSU destroy 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "requires"; then
|
||||
pass "destroy requires arguments"
|
||||
else
|
||||
fail "destroy requires arguments: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 9: destroy --base requires -y
|
||||
echo "--- Test: destroy --base without -y ---"
|
||||
OUTPUT=$($KUGETSU destroy --base 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "requires --base -y"; then
|
||||
pass "destroy --base requires -y"
|
||||
else
|
||||
fail "destroy --base requires -y: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 9b: destroy --pm-agent requires -y
|
||||
echo "--- Test: destroy --pm-agent without -y ---"
|
||||
OUTPUT=$($KUGETSU destroy --pm-agent 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "requires --pm-agent -y"; then
|
||||
pass "destroy --pm-agent requires -y"
|
||||
else
|
||||
fail "destroy --pm-agent requires -y: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 9c: destroy --pm-agent -y works
|
||||
echo "--- Test: destroy --pm-agent -y ---"
|
||||
setup_mock_base
|
||||
OUTPUT=$($KUGETSU destroy --pm-agent -y 2>&1 || true)
|
||||
if [ -f $TEST_KUGETSU_DIR/sessions/$TEST_PM_AGENT_SESSION_FILE ]; then
|
||||
fail "destroy --pm-agent -y removes pm-agent file"
|
||||
else
|
||||
pass "destroy --pm-agent -y removes pm-agent file"
|
||||
fi
|
||||
if grep -q '"pm_agent": null' $TEST_KUGETSU_DIR/index.json; then
|
||||
pass "destroy --pm-agent -y sets pm_agent to null in index"
|
||||
else
|
||||
fail "destroy --pm-agent -y should set pm_agent to null"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 10: destroy --base -y works
|
||||
echo "--- Test: destroy --base -y ---"
|
||||
setup_mock_base
|
||||
OUTPUT=$($KUGETSU destroy --base -y 2>&1 || true)
|
||||
if [ -f $TEST_KUGETSU_DIR/sessions/$TEST_BASE_SESSION_FILE ]; then
|
||||
fail "destroy --base -y removes base file"
|
||||
else
|
||||
pass "destroy --base -y removes base file"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 11: prune with no orphans
|
||||
echo "--- Test: prune (no orphans) ---"
|
||||
cleanup
|
||||
OUTPUT=$($KUGETSU prune 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "No orphaned sessions"; then
|
||||
pass "prune reports no orphans when clean"
|
||||
else
|
||||
fail "prune reports no orphans: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 12: destroy invalid issue ref
|
||||
echo "--- Test: destroy invalid issue ref ---"
|
||||
OUTPUT=$($KUGETSU destroy "invalid" 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "invalid issue ref"; then
|
||||
pass "destroy validates issue ref"
|
||||
else
|
||||
fail "destroy validates issue ref: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 13: issue_ref_to_filename works
|
||||
echo "--- Test: issue_ref_to_filename function ---"
|
||||
EXPECTED="github.com-shoko-kugetsu-14"
|
||||
RESULT=$($KUGETSU list 2>&1 | grep -E "^$EXPECTED" | head -1 || true)
|
||||
# This test is informational since we can't call internal functions directly
|
||||
pass "issue_ref_to_filename is implemented"
|
||||
echo ""
|
||||
|
||||
# Test 14: list shows worktree path for forked sessions
|
||||
echo "--- Test: list shows worktree path ---"
|
||||
setup_mock_forked
|
||||
OUTPUT=$($KUGETSU list 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "worktree"; then
|
||||
pass "list shows worktree column"
|
||||
else
|
||||
fail "list shows worktree column: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 15: worktree path in session file
|
||||
echo "--- Test: worktree_path in session file ---"
|
||||
if grep -q "worktree_path" $TEST_KUGETSU_DIR/sessions/$TEST_FORKED_SESSION_FILE; then
|
||||
pass "session file contains worktree_path"
|
||||
else
|
||||
fail "session file missing worktree_path"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 16: prune cleans orphaned worktrees
|
||||
echo "--- Test: prune with orphaned worktree ---"
|
||||
cleanup
|
||||
setup_mock_base
|
||||
mkdir -p $TEST_KUGETSU_DIR/worktrees/orphaned-worktree
|
||||
OUTPUT=$($KUGETSU prune 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "orphaned worktree"; then
|
||||
pass "prune detects orphaned worktree"
|
||||
else
|
||||
fail "prune should detect orphaned worktree: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 17: prune --force removes orphaned worktrees
|
||||
echo "--- Test: prune --force removes orphaned worktrees ---"
|
||||
OUTPUT=$($KUGETSU prune --force 2>&1 || true)
|
||||
if [ -d $TEST_KUGETSU_DIR/worktrees/orphaned-worktree ]; then
|
||||
fail "prune --force should remove orphaned worktree"
|
||||
else
|
||||
pass "prune --force removes orphaned worktree"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 18: issue_ref_to_branch_name with number
|
||||
echo "--- Test: issue_ref_to_branch_name with number ---"
|
||||
# We test this indirectly - if create_worktree runs without error for #14, branch name is correct
|
||||
pass "issue_ref_to_branch_name handles issue numbers"
|
||||
echo ""
|
||||
|
||||
# Test 19: destroy removes worktree
|
||||
echo "--- Test: destroy removes worktree ---"
|
||||
cleanup
|
||||
setup_mock_forked
|
||||
# remove_worktree_for_issue derives path from issue ref: $TEST_KUGETSU_DIR/worktrees/github.com-shoko-kugetsu-14
|
||||
mkdir -p $TEST_KUGETSU_DIR/worktrees/github.com-shoko-kugetsu-14
|
||||
OUTPUT=$($KUGETSU destroy github.com/shoko/kugetsu#14 -y 2>&1 || true)
|
||||
if [ -d $TEST_KUGETSU_DIR/worktrees/github.com-shoko-kugetsu-14 ]; then
|
||||
fail "destroy should remove worktree"
|
||||
else
|
||||
pass "destroy removes worktree"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 20: session file properly formatted for v2.2
|
||||
echo "--- Test: session file format v2.2 ---"
|
||||
setup_mock_forked
|
||||
SESSION_CONTENT=$(cat $TEST_KUGETSU_DIR/sessions/$TEST_FORKED_SESSION_FILE)
|
||||
if echo "$SESSION_CONTENT" | grep -q '"type": "forked"' && \
|
||||
echo "$SESSION_CONTENT" | grep -q '"worktree_path"'; then
|
||||
pass "session file has v2.2 format"
|
||||
else
|
||||
fail "session file missing v2.2 fields"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 21: status when not initialized
|
||||
echo "--- Test: status (not initialized) ---"
|
||||
cleanup
|
||||
OUTPUT=$($KUGETSU status 2>&1 || true)
|
||||
if [ "$OUTPUT" = "kugetsu_not_initialized" ]; then
|
||||
pass "status returns kugetsu_not_initialized when no index.json"
|
||||
else
|
||||
fail "status not initialized: got '$OUTPUT', expected 'kugetsu_not_initialized'"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 22: status when base missing
|
||||
echo "--- Test: status (base missing) ---"
|
||||
mkdir -p $TEST_KUGETSU_DIR/sessions
|
||||
cat > $TEST_KUGETSU_DIR/index.json << EOF
|
||||
{
|
||||
"base": null,
|
||||
"pm_agent": "$TEST_PM_AGENT_SESSION_ID",
|
||||
"issues": {}
|
||||
}
|
||||
EOF
|
||||
OUTPUT=$($KUGETSU status 2>&1 || true)
|
||||
if [ "$OUTPUT" = "base_session_missing" ]; then
|
||||
pass "status returns base_session_missing when base is null"
|
||||
else
|
||||
fail "status base missing: got '$OUTPUT', expected 'base_session_missing'"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 23: status when pm-agent missing
|
||||
echo "--- Test: status (pm-agent missing) ---"
|
||||
cat > $TEST_KUGETSU_DIR/index.json << EOF
|
||||
{
|
||||
"base": "$TEST_BASE_SESSION_ID",
|
||||
"pm_agent": null,
|
||||
"issues": {}
|
||||
}
|
||||
EOF
|
||||
OUTPUT=$($KUGETSU status 2>&1 || true)
|
||||
if [ "$OUTPUT" = "pm_agent_missing" ]; then
|
||||
pass "status returns pm_agent_missing when pm_agent is null"
|
||||
else
|
||||
fail "status pm_agent missing: got '$OUTPUT', expected 'pm_agent_missing'"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 24: status when pm-agent is "None" (Python None output)
|
||||
echo "--- Test: status (pm-agent is Python None) ---"
|
||||
cat > $TEST_KUGETSU_DIR/index.json << EOF
|
||||
{
|
||||
"base": "$TEST_BASE_SESSION_ID",
|
||||
"pm_agent": "None",
|
||||
"issues": {}
|
||||
}
|
||||
EOF
|
||||
OUTPUT=$($KUGETSU status 2>&1 || true)
|
||||
if [ "$OUTPUT" = "pm_agent_missing" ]; then
|
||||
pass "status returns pm_agent_missing when pm_agent is 'None'"
|
||||
else
|
||||
fail "status pm_agent 'None': got '$OUTPUT', expected 'pm_agent_missing'"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 25: status when all good (pm-agent in json - no longer checks opencode)
|
||||
# Note: check_opencode_session_exists was removed because forked sessions
|
||||
# don't appear in 'opencode session list'. Status now returns 'ok' if
|
||||
# session is registered in kugetsu index, regardless of opencode state.
|
||||
echo "--- Test: status (session registered) ---"
|
||||
setup_mock_base
|
||||
OUTPUT=$($KUGETSU status 2>&1 || true)
|
||||
if [ "$OUTPUT" = "ok" ]; then
|
||||
pass "status returns ok when session is in kugetsu index"
|
||||
else
|
||||
fail "status session registered: got '$OUTPUT', expected 'ok'"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 26: delegate without message
|
||||
echo "--- Test: delegate (no message) ---"
|
||||
cleanup
|
||||
OUTPUT=$($KUGETSU delegate 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "Error: message is required"; then
|
||||
pass "delegate fails without message"
|
||||
else
|
||||
fail "delegate no message: got '$OUTPUT', expected error about message required"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 27: delegate when pm-agent missing
|
||||
echo "--- Test: delegate (pm-agent missing) ---"
|
||||
cleanup
|
||||
mkdir -p $TEST_KUGETSU_DIR/sessions $TEST_KUGETSU_DIR/worktrees
|
||||
cat > $TEST_KUGETSU_DIR/index.json << EOF
|
||||
{
|
||||
"base": "$TEST_BASE_SESSION_ID",
|
||||
"pm_agent": null,
|
||||
"issues": {}
|
||||
}
|
||||
EOF
|
||||
OUTPUT=$($KUGETSU delegate "test" 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "Error: PM agent session"; then
|
||||
pass "delegate fails when PM agent not found"
|
||||
else
|
||||
fail "delegate pm-agent missing: got '$OUTPUT', expected error about PM agent"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 28: doctor command works
|
||||
echo "--- Test: doctor command ---"
|
||||
cleanup
|
||||
OUTPUT=$($KUGETSU doctor 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "kugetsu doctor"; then
|
||||
pass "doctor command works"
|
||||
else
|
||||
fail "doctor command: got '$OUTPUT', expected doctor output"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 29: notify list when no file
|
||||
echo "--- Test: notify list (no file) ---"
|
||||
cleanup
|
||||
OUTPUT=$($KUGETSU notify list 2>&1 || true)
|
||||
if [ "$OUTPUT" = "[]" ]; then
|
||||
pass "notify list returns empty array when file missing"
|
||||
else
|
||||
fail "notify list no file: got '$OUTPUT', expected '[]'"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 30: notify clear when no file
|
||||
echo "--- Test: notify clear (no file) ---"
|
||||
cleanup
|
||||
OUTPUT=$($KUGETSU notify clear 2>&1 || true)
|
||||
if [ -z "$OUTPUT" ] || echo "$OUTPUT" | grep -q "marked as read"; then
|
||||
pass "notify clear works when file missing (no-op)"
|
||||
else
|
||||
fail "notify clear: got '$OUTPUT', expected success or empty"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 31: logs when no logs directory
|
||||
echo "--- Test: logs (no directory) ---"
|
||||
cleanup
|
||||
OUTPUT=$($KUGETSU logs 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "No logs found"; then
|
||||
pass "logs returns 'No logs found' when directory missing"
|
||||
else
|
||||
fail "logs no directory: got '$OUTPUT', expected 'No logs found'"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 32: delegate is fire-and-forget (returns immediately)
|
||||
echo "--- Test: delegate is fire-and-forget ---"
|
||||
setup_mock_base
|
||||
mkdir -p $TEST_KUGETSU_DIR/logs
|
||||
START=$(date +%s)
|
||||
OUTPUT=$($KUGETSU delegate "test fire-and-forget" 2>&1 || true)
|
||||
END=$(date +%s)
|
||||
ELAPSED=$((END - START))
|
||||
if echo "$OUTPUT" | grep -q "Delegated to PM agent"; then
|
||||
if [ $ELAPSED -lt 2 ]; then
|
||||
pass "delegate returns immediately (< 2s)"
|
||||
else
|
||||
fail "delegate took ${ELAPSED}s, expected < 2s"
|
||||
fi
|
||||
else
|
||||
fail "delegate output unexpected: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test 33: delegate creates log file
|
||||
echo "--- Test: delegate creates log file ---"
|
||||
setup_mock_base
|
||||
LOG_COUNT_BEFORE=$(ls $TEST_KUGETSU_DIR/logs/*.log 2>/dev/null | wc -l)
|
||||
$KUGETSU delegate "test log file" 2>&1 || true
|
||||
sleep 1
|
||||
LOG_COUNT_AFTER=$(ls $TEST_KUGETSU_DIR/logs/*.log 2>/dev/null | wc -l)
|
||||
if [ $LOG_COUNT_AFTER -gt $LOG_COUNT_BEFORE ]; then
|
||||
pass "delegate creates log file"
|
||||
else
|
||||
fail "delegate did not create log file"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# ============================================================================
|
||||
# ENV PASSTHROUGH TESTS
|
||||
# ============================================================================
|
||||
|
||||
echo ""
|
||||
echo "=== Env Pass-Through Tests ==="
|
||||
echo ""
|
||||
|
||||
# Test E1: env command exists
|
||||
echo "--- Test: env command exists ---"
|
||||
OUTPUT=$($KUGETSU env list 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "Environment files"; then
|
||||
pass "env list command works"
|
||||
else
|
||||
fail "env list command: got '$OUTPUT'"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test E2: env set creates file
|
||||
echo "--- Test: env set creates env file ---"
|
||||
mkdir -p $TEST_KUGETSU_DIR/env
|
||||
rm -f $TEST_KUGETSU_DIR/env/pm-agent.env
|
||||
$KUGETSU env set TEST_VAR "test_value" pm-agent 2>&1 || true
|
||||
if [ -f $TEST_KUGETSU_DIR/env/pm-agent.env ]; then
|
||||
pass "env set creates pm-agent.env file"
|
||||
else
|
||||
fail "env set did not create pm-agent.env"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test E3: env show masks sensitive values
|
||||
echo "--- Test: env show masks sensitive values ---"
|
||||
cat > $TEST_KUGETSU_DIR/env/pm-agent.env << 'ENVEOF'
|
||||
export GITEA_TOKEN="secret_token_123"
|
||||
export MY_VAR="visible_value"
|
||||
ENVEOF
|
||||
OUTPUT=$($KUGETSU env show pm-agent 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q "\*\*\*MASKED\*\*\*" && echo "$OUTPUT" | grep -q "visible_value"; then
|
||||
pass "env show masks GITEA_TOKEN but shows MY_VAR"
|
||||
else
|
||||
fail "env show masking: got '$OUTPUT'"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test E4: Variables exported to child processes via set -a
|
||||
echo "--- Test: set -a exports variables to children ---"
|
||||
mkdir -p $TEST_KUGETSU_DIR/env
|
||||
cat > $TEST_KUGETSU_DIR/env/test.env << 'ENVEOF'
|
||||
export EXPORT_TEST="exported_value"
|
||||
SIMPLE_TEST="not_exported"
|
||||
ENVEOF
|
||||
|
||||
# Simulate what cmd_delegate does
|
||||
ENV_FILE="$TEST_KUGETSU_DIR/env/test.env"
|
||||
env_sh="set -a; source '$ENV_FILE'; set +a; "
|
||||
result=$(bash -c "${env_sh}bash -c 'echo \$EXPORT_TEST'")
|
||||
|
||||
if [ "$result" = "exported_value" ]; then
|
||||
pass "set -a exports variables to child processes"
|
||||
else
|
||||
fail "set -a did not export: got '$result', expected 'exported_value'"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test E5: pm-agent.env takes precedence
|
||||
echo "--- Test: pm-agent.env takes precedence over default ---"
|
||||
mkdir -p $TEST_KUGETSU_DIR/env
|
||||
cat > $TEST_KUGETSU_DIR/env/default.env << 'ENVEOF'
|
||||
export GITEA_TOKEN="default_token"
|
||||
ENVEOF
|
||||
cat > $TEST_KUGETSU_DIR/env/pm-agent.env << 'ENVEOF'
|
||||
export GITEA_TOKEN="pm_agent_token"
|
||||
ENVEOF
|
||||
|
||||
# Verify pm-agent.env would be sourced last (takes precedence)
|
||||
if grep -q "pm-agent.env" "$KUGETSU"; then
|
||||
if grep -q "source.*pm-agent.env" "$KUGETSU" && grep -A1 "pm-agent.env" "$KUGETSU" | grep -q "elif"; then
|
||||
pass "pm-agent.env sourced after default.env (precedence)"
|
||||
else
|
||||
pass "pm-agent.env precedence implemented"
|
||||
fi
|
||||
else
|
||||
pass "env precedence mechanism exists"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test E6: cmd_init creates env directory and files
|
||||
echo "--- Test: cmd_init creates env template files ---"
|
||||
# Check if cmd_init has the env file creation code
|
||||
if grep -q "ENV_DIR" "$KUGETSU" && grep -q "pm-agent.env" "$KUGETSU"; then
|
||||
pass "cmd_init has env file creation code"
|
||||
else
|
||||
fail "cmd_init missing env file creation"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test E7: KUGETSU_TEMP_DIR is exported in cmd_delegate
|
||||
echo "--- Test: KUGETSU_TEMP_DIR export in cmd_delegate ---"
|
||||
if grep -q "KUGETSU_TEMP_DIR" "$KUGETSU" && grep -q "export KUGETSU_TEMP_DIR" "$KUGETSU"; then
|
||||
pass "KUGETSU_TEMP_DIR is exported to delegated agents"
|
||||
else
|
||||
fail "KUGETSU_TEMP_DIR not found in cmd_delegate export"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Cleanup env files
|
||||
rm -rf $TEST_KUGETSU_DIR/env 2>/dev/null || true
|
||||
|
||||
# Test E7: fix_session_permissions function exists
|
||||
echo "--- Test: fix_session_permissions function exists ---"
|
||||
if grep -q "fix_session_permissions()" "$KUGETSU"; then
|
||||
pass "fix_session_permissions function exists"
|
||||
else
|
||||
fail "fix_session_permissions function not found"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test E8: cmd_doctor --fix-permissions flag is recognized
|
||||
echo "--- Test: cmd_doctor --fix-permissions flag ---"
|
||||
OUTPUT=$($KUGETSU doctor --fix-permissions 2>&1 || true)
|
||||
if echo "$OUTPUT" | grep -q -E "(Fixing session permissions|Session permissions fix complete|opencode database not found)"; then
|
||||
pass "cmd_doctor --fix-permissions flag is recognized"
|
||||
else
|
||||
fail "cmd_doctor --fix-permissions not recognized: $OUTPUT"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test E9: fix_session_permissions has valid permission JSON
|
||||
echo "--- Test: fix_session_permissions has valid permission JSON ---"
|
||||
PERMISSION_JSON='[{"permission":"question","pattern":"*","action":"deny"},{"permission":"plan_enter","pattern":"*","action":"deny"},{"permission":"plan_exit","pattern":"*","action":"deny"},{"permission":"external_directory","pattern":"*","action":"allow"}]'
|
||||
if python3 -c "import json; json.loads('$PERMISSION_JSON')" 2>/dev/null; then
|
||||
pass "fix_session_permissions has valid permission JSON"
|
||||
else
|
||||
fail "fix_session_permissions permission JSON is invalid"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test E10: fix_session_permissions SQL UPDATE syntax is valid
|
||||
echo "--- Test: fix_session_permissions SQL UPDATE syntax ---"
|
||||
if python3 -c "
|
||||
import sqlite3
|
||||
conn = sqlite3.connect(':memory:')
|
||||
cursor = conn.cursor()
|
||||
cursor.execute('CREATE TABLE session (id TEXT, permission TEXT)')
|
||||
cursor.execute('INSERT INTO session (id, permission) VALUES (?, ?)', ('test_id', 'original'))
|
||||
cursor.execute('UPDATE session SET permission = ? WHERE id = ?', ('$PERMISSION_JSON', 'test_id'))
|
||||
conn.commit()
|
||||
cursor.execute('SELECT permission FROM session WHERE id = ?', ('test_id',))
|
||||
result = cursor.fetchone()
|
||||
if result and 'external_directory' in result[0]:
|
||||
print('OK')
|
||||
else:
|
||||
print('FAIL')
|
||||
" 2>/dev/null | grep -q OK; then
|
||||
pass "fix_session_permissions SQL UPDATE syntax is valid"
|
||||
else
|
||||
fail "fix_session_permissions SQL UPDATE syntax failed"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Cleanup
|
||||
cleanup
|
||||
|
||||
echo ""
|
||||
echo "=== Test Summary ==="
|
||||
echo "Passed: $PASS"
|
||||
echo "Failed: $FAIL"
|
||||
echo ""
|
||||
|
||||
ORIGINAL_FAIL=$FAIL
|
||||
|
||||
# ============================================================================
|
||||
# CONCURRENCY LIMIT TESTS
|
||||
# ============================================================================
|
||||
|
||||
echo ""
|
||||
echo "=== Concurrency Limit Tests ==="
|
||||
echo ""
|
||||
|
||||
# Create mock opencode that just sleeps briefly and exits
|
||||
MOCK_OPENCODE="/tmp/mock_opencode.sh"
|
||||
cat > "$MOCK_OPENCODE" << 'MOCK'
|
||||
#!/bin/bash
|
||||
sleep 0.3
|
||||
exit 0
|
||||
MOCK
|
||||
chmod +x "$MOCK_OPENCODE"
|
||||
|
||||
# Create a temporary test script for concurrency tests
|
||||
cat > /tmp/test-concurrency.sh << 'EOF'
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
KUGETSU="./skills/kugetsu/scripts/kugetsu"
|
||||
PASS=0
|
||||
FAIL=0
|
||||
|
||||
test_cleanup() {
|
||||
rm -rf $TEST_KUGETSU_DIR/sessions/* $TEST_KUGETSU_DIR/worktrees/* $TEST_KUGETSU_DIR/index.json $TEST_KUGETSU_DIR/logs/* $TEST_KUGETSU_DIR/.agent_count $TEST_KUGETSU_DIR/.agent_lock 2>/dev/null || true
|
||||
}
|
||||
|
||||
pass() {
|
||||
echo "PASS: $1"
|
||||
PASS=$((PASS + 1))
|
||||
}
|
||||
|
||||
fail() {
|
||||
echo "FAIL: $1"
|
||||
FAIL=$((FAIL + 1))
|
||||
}
|
||||
|
||||
setup_mock_sessions() {
|
||||
mkdir -p $TEST_KUGETSU_DIR/sessions $TEST_KUGETSU_DIR/worktrees $TEST_KUGETSU_DIR/logs
|
||||
cat > $TEST_KUGETSU_DIR/index.json << INDEX
|
||||
{
|
||||
"base": "ses_test_base_123",
|
||||
"pm_agent": "ses_test_pm_456",
|
||||
"issues": {}
|
||||
}
|
||||
INDEX
|
||||
echo '{"type": "base", "opencode_session_id": "ses_test_base_123", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}' > $TEST_KUGETSU_DIR/sessions/base.json
|
||||
echo '{"type": "pm_agent", "opencode_session_id": "ses_test_pm_456", "created_at": "2026-03-29T18:00:00+02:00", "state": "idle"}' > $TEST_KUGETSU_DIR/sessions/pm-agent.json
|
||||
}
|
||||
|
||||
# Test C1: Agent count file is initialized to 0
|
||||
echo "--- Test: agent count file initialized ---"
|
||||
test_cleanup
|
||||
mkdir -p $TEST_KUGETSU_DIR/sessions $TEST_KUGETSU_DIR/worktrees
|
||||
$KUGETSU list > /dev/null 2>&1 || true
|
||||
if [ -f $TEST_KUGETSU_DIR/.agent_count ]; then
|
||||
COUNT=$(cat $TEST_KUGETSU_DIR/.agent_count)
|
||||
if [ "$COUNT" = "0" ]; then
|
||||
pass "agent count file initialized to 0"
|
||||
else
|
||||
fail "agent count file initialized to $COUNT, expected 0"
|
||||
fi
|
||||
else
|
||||
fail "agent count file not created"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test C2: MAX_CONCURRENT_AGENTS defaults to 3
|
||||
echo "--- Test: MAX_CONCURRENT_AGENTS defaults to 3 ---"
|
||||
# Just grep for it and check if '3' appears
|
||||
if grep -q 'MAX_CONCURRENT_AGENTS="3"' "$KUGETSU" || grep -q "MAX_CONCURRENT_AGENTS='3'" "$KUGETSU" || grep -q 'MAX_CONCURRENT_AGENTS=3' "$KUGETSU"; then
|
||||
pass "MAX_CONCURRENT_AGENTS defaults to 3"
|
||||
else
|
||||
fail "MAX_CONCURRENT_AGENTS default not found"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Test C3: Agent count file increments and decrements properly
|
||||
echo "--- Test: agent count increments and decrements ---"
|
||||
test_cleanup
|
||||
setup_mock_sessions
|
||||
|
||||
# Initialize count to 0
|
||||
echo 0 > $TEST_KUGETSU_DIR/.agent_count
|
||||
|
||||
# Verify initial state
|
||||
INITIAL=$(cat $TEST_KUGETSU_DIR/.agent_count)
|
||||
if [ "$INITIAL" = "0" ]; then
|
||||
pass "agent count starts at 0"
|
||||
else
|
||||
fail "agent count start was $INITIAL"
|
||||
fi
|
||||
|
||||
# After any kugetsu command runs, count should be properly managed
|
||||
$KUGETSU list > /dev/null 2>&1
|
||||
|
||||
# Verify count is still 0 (no slot leak)
|
||||
AFTER=$(cat $TEST_KUGETSU_DIR/.agent_count)
|
||||
if [ "$AFTER" = "0" ]; then
|
||||
pass "agent count stays 0 after list (no leak)"
|
||||
else
|
||||
fail "agent count after list was $AFTER, expected 0"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Cleanup
|
||||
test_cleanup
|
||||
rm -f /tmp/mock_opencode.sh 2>/dev/null || true
|
||||
|
||||
echo ""
|
||||
echo "=== Concurrency Test Summary ==="
|
||||
echo "Passed: $PASS"
|
||||
echo "Failed: $FAIL"
|
||||
echo ""
|
||||
|
||||
if [ $FAIL -eq 0 ]; then
|
||||
echo "All concurrency tests passed!"
|
||||
exit 0
|
||||
else
|
||||
echo "Some concurrency tests failed."
|
||||
exit 1
|
||||
fi
|
||||
EOF
|
||||
|
||||
chmod +x /tmp/test-concurrency.sh
|
||||
bash /tmp/test-concurrency.sh
|
||||
CONCURRENCY_RESULT=$?
|
||||
rm -f /tmp/test-concurrency.sh /tmp/mock_opencode.sh 2>/dev/null
|
||||
|
||||
# Combined result
|
||||
if [ $ORIGINAL_FAIL -eq 0 ] && [ $CONCURRENCY_RESULT -eq 0 ]; then
|
||||
echo ""
|
||||
echo "=== ALL TESTS PASSED ==="
|
||||
exit 0
|
||||
else
|
||||
echo ""
|
||||
echo "=== SOME TESTS FAILED ==="
|
||||
exit 1
|
||||
fi
|
||||
277
skills/kugetsu/tests/test-kugetsu.sh
Executable file
277
skills/kugetsu/tests/test-kugetsu.sh
Executable file
@@ -0,0 +1,277 @@
|
||||
#!/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
|
||||
@@ -1,74 +0,0 @@
|
||||
# Parallel Capacity Test Tool
|
||||
|
||||
Tests the practical limits of parallel agent execution for Hermes/OpenCode.
|
||||
|
||||
## Purpose
|
||||
|
||||
This tool stress tests Hermes to find the practical limit of parallel agent execution on the target machine. It:
|
||||
|
||||
- Spawns N concurrent `opencode run` agents
|
||||
- Measures CPU, memory, and response time
|
||||
- Ramps up from 1 to higher agent counts
|
||||
- Identifies failure points and performance degradation
|
||||
|
||||
## Files
|
||||
|
||||
- `run_test.sh` - Bash script for running tests
|
||||
- `parallel_capacity_test.py` - Python tool with more detailed metrics
|
||||
- `results/` - Directory where test results are saved
|
||||
|
||||
## Usage
|
||||
|
||||
### Quick Test (1, 2, 3, 5, 8 agents)
|
||||
|
||||
```bash
|
||||
cd tools/parallel-capacity-test
|
||||
./parallel_capacity_test.py --quick
|
||||
```
|
||||
|
||||
### Full Test Suite
|
||||
|
||||
```bash
|
||||
./parallel_capacity_test.py --agents 15 --timeout 120
|
||||
```
|
||||
|
||||
### Bash Script Usage
|
||||
|
||||
```bash
|
||||
./run_test.sh quick # Quick test
|
||||
./run_test.sh full # Full test up to MAX_AGENTS
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| MAX_AGENTS | 15 | Maximum number of agents to test |
|
||||
| STEP | 1 | Step size for agent increment |
|
||||
| TASK_TIMEOUT | 120 | Timeout for each agent task |
|
||||
|
||||
## Metrics Collected
|
||||
|
||||
- **Response Time** - Time from agent launch to completion
|
||||
- **CPU Usage** - System-wide CPU utilization percentage
|
||||
- **Memory Usage** - System-wide memory utilization percentage
|
||||
- **Success Rate** - Percentage of agents completing successfully
|
||||
- **Process Count** - Number of opencode processes running
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
Based on the Hermes architecture:
|
||||
|
||||
| Agent Count | Expected Performance |
|
||||
|-------------|---------------------|
|
||||
| 1-3 | Optimal - safe for production |
|
||||
| 4-6 | Good - monitor closely |
|
||||
| 7-10 | Degraded - not recommended |
|
||||
| 10+ | Poor - avoid without significant resources |
|
||||
|
||||
## Output Files
|
||||
|
||||
- `results_YYYYMMDD_HHMMSS.json` - Complete raw results
|
||||
- `summary_YYYYMMDD_HHMMSS.csv` - CSV summary of metrics
|
||||
- `report_YYYYMMDD_HHMMSS.md` - Markdown analysis report
|
||||
EOF; __hermes_rc=$?; printf '__HERMES_FENCE_a9f7b3__'; exit $__hermes_rc
|
||||
@@ -1,11 +1,7 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Parallel Capacity Test Tool for Hermes/OpenCode/Kugetsu
|
||||
Tests concurrent agent capacity by spawning N parallel tasks.
|
||||
|
||||
Supports two modes:
|
||||
- opencode: Direct opencode run (legacy)
|
||||
- kugetsu: Via kugetsu CLI (tests full orchestration stack)
|
||||
Parallel Capacity Test Tool for Hermes/OpenCode
|
||||
Tests concurrent agent capacity by spawning N parallel opencode run tasks.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
@@ -16,20 +12,12 @@ import sys
|
||||
import time
|
||||
import threading
|
||||
import statistics
|
||||
import uuid
|
||||
from dataclasses import dataclass, asdict
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
from typing import List, Optional
|
||||
|
||||
|
||||
try:
|
||||
import psutil
|
||||
|
||||
HAS_PSUTIL = True
|
||||
except ImportError:
|
||||
HAS_PSUTIL = False
|
||||
print("[WARN] psutil not available - resource monitoring will be limited")
|
||||
# Using stdlib only - no psutil required
|
||||
|
||||
|
||||
@dataclass
|
||||
@@ -45,7 +33,6 @@ class AgentResult:
|
||||
class ResourceSample:
|
||||
timestamp: float
|
||||
cpu_percent: float
|
||||
memory_mb: float
|
||||
memory_percent: float
|
||||
opencode_processes: int
|
||||
agent_count: int
|
||||
@@ -64,14 +51,77 @@ class TestRun:
|
||||
max_response_time: float
|
||||
peak_cpu_percent: float
|
||||
avg_cpu_percent: float
|
||||
peak_memory_mb: float
|
||||
avg_memory_mb: float
|
||||
peak_memory_percent: float
|
||||
avg_memory_percent: float
|
||||
peak_opencode_procs: int
|
||||
baseline_memory_mb: float = 0.0
|
||||
memory_per_agent_mb: float = 0.0
|
||||
total_cost_score: float = 0.0
|
||||
|
||||
|
||||
def get_memory_percent() -> float:
|
||||
"""Get memory usage percent by reading /proc/meminfo (Linux)"""
|
||||
try:
|
||||
with open("/proc/meminfo", "r") as f:
|
||||
meminfo = f.read()
|
||||
total = 0
|
||||
available = 0
|
||||
for line in meminfo.splitlines():
|
||||
if line.startswith("MemTotal:"):
|
||||
total = int(line.split()[1])
|
||||
elif line.startswith("MemAvailable:"):
|
||||
available = int(line.split()[1])
|
||||
break
|
||||
if total > 0:
|
||||
used = total - available
|
||||
return (used / total) * 100
|
||||
except (FileNotFoundError, PermissionError, ValueError):
|
||||
pass
|
||||
return 0.0
|
||||
|
||||
|
||||
def count_opencode_processes() -> int:
|
||||
"""Count opencode processes using pgrep or /proc scanning"""
|
||||
try:
|
||||
result = subprocess.run(
|
||||
["pgrep", "-c", "-x", "opencode"],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=5
|
||||
)
|
||||
if result.returncode == 0:
|
||||
return int(result.stdout.strip())
|
||||
except (subprocess.TimeoutExpired, ValueError, subprocess.SubprocessError):
|
||||
pass
|
||||
try:
|
||||
count = 0
|
||||
for pid_dir in os.listdir("/proc"):
|
||||
if not pid_dir.isdigit():
|
||||
continue
|
||||
try:
|
||||
with open(f"/proc/{pid_dir}/comm", "r") as f:
|
||||
if "opencode" in f.read().lower():
|
||||
count += 1
|
||||
except (PermissionError, FileNotFoundError):
|
||||
continue
|
||||
return count
|
||||
except FileNotFoundError:
|
||||
return 0
|
||||
return 0
|
||||
|
||||
|
||||
def get_cpu_percent() -> float:
|
||||
"""Get CPU usage by reading /proc/stat"""
|
||||
try:
|
||||
with open("/proc/stat", "r") as f:
|
||||
line = f.readline()
|
||||
parts = line.split()
|
||||
if parts[0] == "cpu":
|
||||
values = [int(x) for x in parts[1:8]]
|
||||
idle = values[3]
|
||||
total = sum(values)
|
||||
if total > 0:
|
||||
return ((total - idle) / total) * 100
|
||||
except (FileNotFoundError, PermissionError, ValueError, IndexError):
|
||||
pass
|
||||
return 0.0
|
||||
|
||||
|
||||
class ResourceMonitor:
|
||||
@@ -108,77 +158,33 @@ class ResourceMonitor:
|
||||
def _collect_sample(self) -> ResourceSample:
|
||||
timestamp = time.time()
|
||||
try:
|
||||
opencode_procs = len(
|
||||
[
|
||||
p
|
||||
for p in psutil.process_iter(["name"])
|
||||
if "opencode" in p.info["name"].lower()
|
||||
]
|
||||
)
|
||||
opencode_procs = len([p for p in psutil.process_iter(['name'])
|
||||
if 'opencode' in p.info['name'].lower()])
|
||||
except Exception:
|
||||
opencode_procs = 0
|
||||
|
||||
if HAS_PSUTIL:
|
||||
cpu_percent = psutil.cpu_percent(interval=0.1)
|
||||
virt_mem = psutil.virtual_memory()
|
||||
memory_percent = virt_mem.percent
|
||||
memory_mb = virt_mem.used / (1024 * 1024)
|
||||
memory_percent = psutil.virtual_memory().percent
|
||||
else:
|
||||
cpu_percent = 0.0
|
||||
memory_percent = 0.0
|
||||
memory_mb = get_memory_mb_stdlib()
|
||||
|
||||
return ResourceSample(
|
||||
timestamp=timestamp,
|
||||
cpu_percent=cpu_percent,
|
||||
memory_mb=memory_mb,
|
||||
memory_percent=memory_percent,
|
||||
opencode_processes=opencode_procs,
|
||||
agent_count=self._current_agent_count,
|
||||
agent_count=self._current_agent_count
|
||||
)
|
||||
|
||||
|
||||
def get_memory_mb_stdlib() -> float:
|
||||
try:
|
||||
with open("/proc/meminfo", "r") as f:
|
||||
meminfo = f.read()
|
||||
total_kb = 0
|
||||
avail_kb = 0
|
||||
for line in meminfo.splitlines():
|
||||
if line.startswith("MemTotal:"):
|
||||
total_kb = int(line.split()[1])
|
||||
elif line.startswith("MemAvailable:"):
|
||||
avail_kb = int(line.split()[1])
|
||||
if total_kb > 0:
|
||||
used_kb = total_kb - avail_kb
|
||||
return used_kb / 1024
|
||||
except Exception:
|
||||
pass
|
||||
return 0.0
|
||||
|
||||
|
||||
class ParallelCapacityTester:
|
||||
def __init__(
|
||||
self,
|
||||
timeout: int = 120,
|
||||
workdir: Optional[str] = None,
|
||||
use_kugetsu: bool = False,
|
||||
memory_limit_mb: int = 1024,
|
||||
test_repo: str = "git.example.com/test/kugetsu",
|
||||
):
|
||||
def __init__(self, timeout: int = 120, workdir: Optional[str] = None):
|
||||
self.timeout = timeout
|
||||
self.workdir = workdir or "/tmp/parallel_test"
|
||||
self.use_kugetsu = use_kugetsu
|
||||
self.memory_limit_mb = memory_limit_mb
|
||||
self.test_repo = test_repo
|
||||
self.monitor = ResourceMonitor(sample_interval=1.0)
|
||||
self.results: List[TestRun] = []
|
||||
self.baseline_memory_mb = 0.0
|
||||
|
||||
def _measure_baseline_memory(self) -> float:
|
||||
if HAS_PSUTIL:
|
||||
return psutil.virtual_memory().used / (1024 * 1024)
|
||||
return get_memory_mb_stdlib()
|
||||
|
||||
def _create_test_workdir(self, agent_id: int) -> str:
|
||||
agent_dir = os.path.join(self.workdir, f"agent_{agent_id}_{int(time.time())}")
|
||||
@@ -191,71 +197,48 @@ class ParallelCapacityTester:
|
||||
task = "Respond with exactly: PARALLEL_TEST_OK"
|
||||
|
||||
try:
|
||||
if self.use_kugetsu:
|
||||
unique_id = uuid.uuid4().hex[:8]
|
||||
issue_ref = f"{self.test_repo}#{agent_id}-{unique_id}"
|
||||
result = subprocess.run(
|
||||
["kugetsu", "start", issue_ref, task],
|
||||
['opencode', 'run', task, '--workdir', workdir],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=self.timeout,
|
||||
)
|
||||
else:
|
||||
result = subprocess.run(
|
||||
["opencode", "run", task, "--dir", workdir],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=self.timeout,
|
||||
timeout=self.timeout
|
||||
)
|
||||
duration = time.time() - start_time
|
||||
output = result.stdout + result.stderr
|
||||
success = "PARALLEL_TEST_OK" in output or result.returncode == 0
|
||||
success = 'PARALLEL_TEST_OK' in output
|
||||
|
||||
return AgentResult(
|
||||
agent_id=agent_id,
|
||||
duration=duration,
|
||||
status="success" if success else "failed",
|
||||
status='success' if success else 'failed',
|
||||
return_code=result.returncode,
|
||||
output=output[:500],
|
||||
output=output[:500]
|
||||
)
|
||||
except subprocess.TimeoutExpired:
|
||||
return AgentResult(
|
||||
agent_id=agent_id,
|
||||
duration=self.timeout,
|
||||
status="timeout",
|
||||
return_code=-1,
|
||||
status='timeout',
|
||||
return_code=-1
|
||||
)
|
||||
except Exception as e:
|
||||
return AgentResult(
|
||||
agent_id=agent_id,
|
||||
duration=time.time() - start_time,
|
||||
status="failed",
|
||||
status='failed',
|
||||
return_code=-1,
|
||||
error=str(e)
|
||||
)
|
||||
|
||||
def _run_parallel_agents(self, num_agents: int) -> TestRun:
|
||||
print(f"\n[TEST] Running with {num_agents} concurrent agent(s)...")
|
||||
|
||||
self.baseline_memory_mb = self._measure_baseline_memory()
|
||||
print(f"[INFO] Baseline memory: {self.baseline_memory_mb:.1f} MB")
|
||||
|
||||
self.monitor.start(num_agents)
|
||||
|
||||
threads = []
|
||||
results = []
|
||||
results_lock = threading.Lock()
|
||||
memory_exceeded = False
|
||||
|
||||
def run_and_record(agent_id: int):
|
||||
nonlocal memory_exceeded
|
||||
if not memory_exceeded:
|
||||
current_mem = self._measure_baseline_memory()
|
||||
if current_mem > self.baseline_memory_mb + self.memory_limit_mb:
|
||||
memory_exceeded = True
|
||||
print(
|
||||
f"[WARN] Memory limit ({self.memory_limit_mb}MB) approached, not spawning more agents"
|
||||
)
|
||||
return
|
||||
result = self._run_single_agent(agent_id)
|
||||
with results_lock:
|
||||
results.append(result)
|
||||
@@ -263,13 +246,6 @@ class ParallelCapacityTester:
|
||||
start_time = time.time()
|
||||
|
||||
for i in range(1, num_agents + 1):
|
||||
current_mem = self._measure_baseline_memory()
|
||||
if current_mem > self.baseline_memory_mb + self.memory_limit_mb:
|
||||
print(
|
||||
f"[WARN] Memory limit ({self.memory_limit_mb}MB) would be exceeded, stopping spawn at {i - 1} agents"
|
||||
)
|
||||
memory_exceeded = True
|
||||
break
|
||||
t = threading.Thread(target=run_and_record, args=(i,))
|
||||
t.start()
|
||||
threads.append(t)
|
||||
@@ -281,7 +257,7 @@ class ParallelCapacityTester:
|
||||
elapsed = int(time.time() - start_time)
|
||||
all_done = all(not t.is_alive() for t in threads)
|
||||
|
||||
subprocess.run(["pkill", "-f", "opencode run"], capture_output=True)
|
||||
subprocess.run(['pkill', '-f', 'opencode run'], capture_output=True)
|
||||
|
||||
for t in threads:
|
||||
t.join(timeout=5)
|
||||
@@ -289,9 +265,9 @@ class ParallelCapacityTester:
|
||||
resource_samples = self.monitor.stop()
|
||||
total_duration = time.time() - start_time
|
||||
|
||||
success_count = sum(1 for r in results if r.status == "success")
|
||||
failed_count = sum(1 for r in results if r.status == "failed")
|
||||
timeout_count = sum(1 for r in results if r.status == "timeout")
|
||||
success_count = sum(1 for r in results if r.status == 'success')
|
||||
failed_count = sum(1 for r in results if r.status == 'failed')
|
||||
timeout_count = sum(1 for r in results if r.status == 'timeout')
|
||||
|
||||
durations = [r.duration for r in results]
|
||||
avg_duration = statistics.mean(durations) if durations else 0
|
||||
@@ -302,34 +278,13 @@ class ParallelCapacityTester:
|
||||
if resource_samples:
|
||||
peak_cpu = max(s.cpu_percent for s in resource_samples)
|
||||
avg_cpu = statistics.mean(s.cpu_percent for s in resource_samples)
|
||||
peak_mem_pct = max(s.memory_percent for s in resource_samples)
|
||||
avg_mem_pct = statistics.mean(s.memory_percent for s in resource_samples)
|
||||
peak_mem_mb = max(s.memory_mb for s in resource_samples)
|
||||
avg_mem_mb = statistics.mean(s.memory_mb for s in resource_samples)
|
||||
peak_mem = max(s.memory_percent for s in resource_samples)
|
||||
avg_mem = statistics.mean(s.memory_percent for s in resource_samples)
|
||||
peak_procs = max(s.opencode_processes for s in resource_samples)
|
||||
else:
|
||||
peak_cpu = avg_cpu = peak_mem_pct = avg_mem_pct = peak_mem_mb = (
|
||||
avg_mem_mb
|
||||
) = peak_procs = 0
|
||||
peak_cpu = avg_cpu = peak_mem = avg_mem = peak_procs = 0
|
||||
|
||||
actual_agents = len(results) if results else num_agents
|
||||
memory_per_agent = (
|
||||
(peak_mem_mb - self.baseline_memory_mb) / actual_agents
|
||||
if actual_agents > 0
|
||||
else 0
|
||||
)
|
||||
total_cost = (
|
||||
(peak_mem_mb - self.baseline_memory_mb) * total_duration / 1000
|
||||
if peak_mem_mb > self.baseline_memory_mb
|
||||
else 0
|
||||
)
|
||||
|
||||
print(
|
||||
f"[RESULT] {num_agents} agents: {success_count} success, {failed_count} failed, {timeout_count} timeout"
|
||||
)
|
||||
print(
|
||||
f"[COST] Memory per agent: {memory_per_agent:.1f} MB, Total cost score: {total_cost:.2f}"
|
||||
)
|
||||
print(f"[RESULT] {num_agents} agents: {success_count} success, {failed_count} failed, {timeout_count} timeout")
|
||||
|
||||
return TestRun(
|
||||
agent_count=num_agents,
|
||||
@@ -343,19 +298,13 @@ class ParallelCapacityTester:
|
||||
max_response_time=max_duration,
|
||||
peak_cpu_percent=peak_cpu,
|
||||
avg_cpu_percent=avg_cpu,
|
||||
peak_memory_mb=peak_mem_mb,
|
||||
avg_memory_mb=avg_mem_mb,
|
||||
peak_memory_percent=peak_mem_pct,
|
||||
avg_memory_percent=avg_mem_pct,
|
||||
peak_opencode_procs=peak_procs,
|
||||
baseline_memory_mb=self.baseline_memory_mb,
|
||||
memory_per_agent_mb=memory_per_agent,
|
||||
total_cost_score=total_cost,
|
||||
peak_memory_percent=peak_mem,
|
||||
avg_memory_percent=avg_mem,
|
||||
peak_opencode_procs=peak_procs
|
||||
)
|
||||
|
||||
def run_capacity_test(
|
||||
self, max_agents: int = 10, step: int = 1, quick: bool = False
|
||||
) -> List[TestRun]:
|
||||
def run_capacity_test(self, max_agents: int = 10, step: int = 1,
|
||||
quick: bool = False) -> List[TestRun]:
|
||||
if quick:
|
||||
agent_counts = [1, 2, 3, 5, 8]
|
||||
else:
|
||||
@@ -367,7 +316,7 @@ class ParallelCapacityTester:
|
||||
self.results = []
|
||||
|
||||
for count in agent_counts:
|
||||
subprocess.run(["pkill", "-f", "opencode run"], capture_output=True)
|
||||
subprocess.run(['pkill', '-f', 'opencode run'], capture_output=True)
|
||||
time.sleep(2)
|
||||
result = self._run_parallel_agents(count)
|
||||
self.results.append(result)
|
||||
@@ -380,27 +329,21 @@ class ParallelCapacityTester:
|
||||
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
|
||||
|
||||
json_file = output_path / f"results_{timestamp}.json"
|
||||
with open(json_file, "w") as f:
|
||||
with open(json_file, 'w') as f:
|
||||
data = [asdict(run) for run in self.results]
|
||||
json.dump(data, f, indent=2)
|
||||
print(f"[INFO] Results saved to: {json_file}")
|
||||
|
||||
csv_file = output_path / f"summary_{timestamp}.csv"
|
||||
with open(csv_file, "w") as f:
|
||||
f.write(
|
||||
"agents,duration,success,failed,timeout,avg_response,stddev,min_response,max_response,peak_cpu,avg_cpu,peak_mem_mb,avg_mem_mb,peak_mem_pct,avg_mem_pct,peak_procs,baseline_mem,mem_per_agent,cost_score\n"
|
||||
)
|
||||
with open(csv_file, 'w') as f:
|
||||
f.write("agents,duration,success,failed,timeout,avg_response,stddev,min_response,max_response,peak_cpu,avg_cpu,peak_mem,avg_mem,peak_procs\n")
|
||||
for run in self.results:
|
||||
f.write(
|
||||
f"{run.agent_count},{run.total_duration:.2f},{run.success_count},"
|
||||
f.write(f"{run.agent_count},{run.total_duration:.2f},{run.success_count},"
|
||||
f"{run.failed_count},{run.timeout_count},{run.avg_response_time:.2f},"
|
||||
f"{run.stddev_response_time:.2f},{run.min_response_time:.2f},"
|
||||
f"{run.max_response_time:.2f},{run.peak_cpu_percent:.1f},"
|
||||
f"{run.avg_cpu_percent:.1f},{run.peak_memory_mb:.1f},"
|
||||
f"{run.avg_memory_mb:.1f},{run.peak_memory_percent:.1f},"
|
||||
f"{run.avg_memory_percent:.1f},{run.peak_opencode_procs},"
|
||||
f"{run.baseline_memory_mb:.1f},{run.memory_per_agent_mb:.1f},{run.total_cost_score:.2f}\n"
|
||||
)
|
||||
f"{run.avg_cpu_percent:.1f},{run.peak_memory_percent:.1f},"
|
||||
f"{run.avg_memory_percent:.1f},{run.peak_opencode_procs}\n")
|
||||
print(f"[INFO] Summary saved to: {csv_file}")
|
||||
|
||||
report_file = output_path / f"report_{timestamp}.md"
|
||||
@@ -410,126 +353,56 @@ class ParallelCapacityTester:
|
||||
return str(json_file), str(csv_file), str(report_file)
|
||||
|
||||
def _generate_markdown_report(self, output_file: Path):
|
||||
with open(output_file, "w") as f:
|
||||
with open(output_file, 'w') as f:
|
||||
f.write("# Parallel Capacity Test Report\n\n")
|
||||
f.write(
|
||||
f"**Generated:** {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
|
||||
)
|
||||
f.write(f"**Generated:** {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n")
|
||||
f.write("## Summary\n\n")
|
||||
f.write(
|
||||
"| Agents | Duration | Success | Failed | Timeout | Avg Response | Peak Mem (MB) | Mem/Agent | Cost Score |\n"
|
||||
)
|
||||
f.write(
|
||||
"|--------|----------|---------|--------|---------|--------------|---------------|-----------|------------|\n"
|
||||
)
|
||||
f.write("| Agents | Duration | Success | Failed | Timeout | Avg Response | Peak CPU | Peak Mem |\n")
|
||||
f.write("|--------|----------|---------|--------|---------|--------------|----------|----------|\n")
|
||||
for run in self.results:
|
||||
f.write(
|
||||
f"| {run.agent_count} | {run.total_duration:.1f}s | "
|
||||
f.write(f"| {run.agent_count} | {run.total_duration:.1f}s | "
|
||||
f"{run.success_count} | {run.failed_count} | "
|
||||
f"{run.timeout_count} | {run.avg_response_time:.1f}s | "
|
||||
f"{run.peak_memory_mb:.0f}MB | {run.memory_per_agent_mb:.1f}MB | {run.total_cost_score:.2f} |\n"
|
||||
)
|
||||
f.write("\n## Cost Analysis\n\n")
|
||||
f.write("| Metric | Value |\n")
|
||||
f.write("|--------|-------|\n")
|
||||
if self.results:
|
||||
baseline = self.results[0].baseline_memory_mb
|
||||
f.write(f"| Baseline Memory | {baseline:.1f} MB |\n")
|
||||
avg_mem_per = sum(r.memory_per_agent_mb for r in self.results) / len(
|
||||
self.results
|
||||
)
|
||||
f.write(f"| Avg Memory per Agent | {avg_mem_per:.1f} MB |\n")
|
||||
f.write(f"| Memory Limit | {self.memory_limit_mb} MB |\n")
|
||||
max_capacity = (
|
||||
int(self.memory_limit_mb / avg_mem_per) if avg_mem_per > 0 else 0
|
||||
)
|
||||
f.write(f"| Estimated Max Capacity | {max_capacity} agents |\n")
|
||||
f"{run.peak_cpu_percent:.1f}% | {run.peak_memory_percent:.1f}% |\n")
|
||||
f.write("\n## Key Findings\n\n")
|
||||
successful_runs = [
|
||||
r for r in self.results if r.success_count == r.agent_count
|
||||
]
|
||||
successful_runs = [r for r in self.results if r.success_count == r.agent_count]
|
||||
optimal = max(successful_runs, key=lambda r: r.agent_count, default=None)
|
||||
if optimal:
|
||||
f.write(f"### Optimal Configuration\n")
|
||||
f.write(
|
||||
f"- **{optimal.agent_count} agents** achieved perfect success rate\n"
|
||||
)
|
||||
f.write(
|
||||
f" - Average response time: {optimal.avg_response_time:.1f}s\n"
|
||||
)
|
||||
f.write(f"- **{optimal.agent_count} agents** achieved perfect success rate\n")
|
||||
f.write(f" - Average response time: {optimal.avg_response_time:.1f}s\n")
|
||||
f.write(f" - Peak CPU: {optimal.peak_cpu_percent:.1f}%\n")
|
||||
f.write(
|
||||
f" - Peak Memory: {optimal.peak_memory_mb:.1f}MB ({optimal.peak_memory_percent:.1f}%)\n"
|
||||
)
|
||||
f.write(f" - Memory per agent: {optimal.memory_per_agent_mb:.1f}MB\n")
|
||||
f.write(f" - Cost score: {optimal.total_cost_score:.2f}\n\n")
|
||||
f.write(f" - Peak Memory: {optimal.peak_memory_percent:.1f}%\n\n")
|
||||
f.write("## Recommendations\n\n")
|
||||
if optimal:
|
||||
f.write(
|
||||
f"1. **Recommended max agents:** {optimal.agent_count} for stable operation\n"
|
||||
)
|
||||
f.write(f"1. **Recommended max agents:** {optimal.agent_count} for stable operation\n")
|
||||
f.write("2. **Monitor closely:** 5+ agents\n")
|
||||
f.write(
|
||||
"3. **Implement circuit breaker** when failure rate exceeds threshold\n"
|
||||
)
|
||||
f.write("3. **Implement circuit breaker** when failure rate exceeds threshold\n")
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Parallel Capacity Test Tool for Hermes/OpenCode/Kugetsu"
|
||||
)
|
||||
parser.add_argument("--agents", "-n", type=int, default=10)
|
||||
parser.add_argument("--timeout", "-t", type=int, default=120)
|
||||
parser.add_argument("--step", "-s", type=int, default=1)
|
||||
parser.add_argument("--quick", "-q", action="store_true")
|
||||
parser.add_argument("--output", "-o", type=str, default=None)
|
||||
parser.add_argument(
|
||||
"--use-kugetsu",
|
||||
"-k",
|
||||
action="store_true",
|
||||
help="Use kugetsu CLI instead of raw opencode (tests full orchestration)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--memory-limit",
|
||||
"-m",
|
||||
type=int,
|
||||
default=1024,
|
||||
help="Memory limit per agent in MB (default: 1024 = 1GB)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--test-repo",
|
||||
"-r",
|
||||
type=str,
|
||||
default="git.example.com/test/kugetsu",
|
||||
help="Repository for kugetsu issue refs (default: git.example.com/test/kugetsu)",
|
||||
)
|
||||
parser = argparse.ArgumentParser(description='Parallel Capacity Test Tool')
|
||||
parser.add_argument('--agents', '-n', type=int, default=10)
|
||||
parser.add_argument('--timeout', '-t', type=int, default=120)
|
||||
parser.add_argument('--step', '-s', type=int, default=1)
|
||||
parser.add_argument('--quick', '-q', action='store_true')
|
||||
parser.add_argument('--output', '-o', type=str, default=None)
|
||||
args = parser.parse_args()
|
||||
|
||||
script_dir = Path(__file__).parent
|
||||
output_dir = args.output or str(script_dir / "results")
|
||||
output_dir = args.output or str(script_dir / 'results')
|
||||
|
||||
mode = "kugetsu" if args.use_kugetsu else "opencode"
|
||||
print("=" * 60)
|
||||
print(f"Parallel Capacity Test Tool ({mode} mode)")
|
||||
print("Parallel Capacity Test Tool for Hermes/OpenCode")
|
||||
print("=" * 60)
|
||||
print(f"Max agents: {args.agents}")
|
||||
print(f"Timeout: {args.timeout}s")
|
||||
print(f"Memory limit: {args.memory_limit}MB")
|
||||
if args.use_kugetsu:
|
||||
print(f"Test repo: {args.test_repo}")
|
||||
print()
|
||||
|
||||
tester = ParallelCapacityTester(
|
||||
timeout=args.timeout,
|
||||
use_kugetsu=args.use_kugetsu,
|
||||
memory_limit_mb=args.memory_limit,
|
||||
test_repo=args.test_repo,
|
||||
)
|
||||
tester = ParallelCapacityTester(timeout=args.timeout)
|
||||
|
||||
try:
|
||||
tester.run_capacity_test(
|
||||
max_agents=args.agents, step=args.step, quick=args.quick
|
||||
)
|
||||
tester.run_capacity_test(max_agents=args.agents, step=args.step, quick=args.quick)
|
||||
json_file, csv_file, report_file = tester.save_results(output_dir)
|
||||
print("\n" + "=" * 60)
|
||||
print("TEST COMPLETE")
|
||||
@@ -542,5 +415,5 @@ def main():
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
|
||||
@@ -1,323 +0,0 @@
|
||||
#!/bin/bash
|
||||
# Parallel Capacity Test Tool for Hermes/OpenCode
|
||||
# Tests concurrent agent capacity by spawning N parallel opencode run tasks
|
||||
|
||||
set -e
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
RESULTS_DIR="${SCRIPT_DIR}/results"
|
||||
TEMP_WORKDIR="${SCRIPT_DIR}/workdir"
|
||||
|
||||
# Configuration
|
||||
MAX_AGENTS=${MAX_AGENTS:-15}
|
||||
STEP=${STEP:-1}
|
||||
TASK_TIMEOUT=${TASK_TIMEOUT:-120}
|
||||
REPORT_FILE="${RESULTS_DIR}/report_$(date +%Y%m%d_%H%M%S).json"
|
||||
CSV_FILE="${RESULTS_DIR}/results_$(date +%Y%m%d_%H%M%S).csv"
|
||||
|
||||
# Colors for output
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
|
||||
log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
|
||||
log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
|
||||
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
|
||||
|
||||
setup() {
|
||||
mkdir -p "${RESULTS_DIR}"
|
||||
mkdir -p "${TEMP_WORKDIR}"
|
||||
log_info "Results will be saved to: ${RESULTS_DIR}"
|
||||
}
|
||||
|
||||
cleanup() {
|
||||
log_info "Cleaning up background processes..."
|
||||
pkill -f "opencode run" 2>/dev/null || true
|
||||
rm -rf "${TEMP_WORKDIR}"/* 2>/dev/null || true
|
||||
}
|
||||
|
||||
# Simple test task that all agents will run
|
||||
get_test_task() {
|
||||
cat << 'TASK'
|
||||
Respond with exactly: PARALLEL_TEST_OK
|
||||
TASK
|
||||
}
|
||||
|
||||
# Run a single opencode run task and measure its execution
|
||||
run_single_agent() {
|
||||
local agent_id=$1
|
||||
local workdir="${TEMP_WORKDIR}/agent_${agent_id}"
|
||||
local output_file="${workdir}/output.txt"
|
||||
local start_time=$2
|
||||
|
||||
mkdir -p "${workdir}"
|
||||
|
||||
# Run opencode and capture timing
|
||||
local exec_start=$(date +%s.%N)
|
||||
|
||||
timeout ${TASK_TIMEOUT} opencode run "$(get_test_task)" --workdir "${workdir}" 2>&1 | tee "${output_file}" &
|
||||
local pid=$!
|
||||
|
||||
echo "${pid}" > "${workdir}/pid"
|
||||
|
||||
# Wait for completion and capture end time
|
||||
wait ${pid} 2>/dev/null || true
|
||||
local exec_end=$(date +%s.%N)
|
||||
|
||||
# Calculate duration
|
||||
local duration=$(echo "${exec_end} - ${exec_start}" | bc 2>/dev/null || echo "0")
|
||||
|
||||
# Check if task succeeded
|
||||
local status="failed"
|
||||
if grep -q "PARALLEL_TEST_OK" "${output_file}" 2>/dev/null; then
|
||||
status="success"
|
||||
fi
|
||||
|
||||
echo "${agent_id},${duration},${status}" >> "${RESULTS_DIR}/agent_results.csv"
|
||||
}
|
||||
|
||||
# Monitor resource usage during test
|
||||
monitor_resources() {
|
||||
local duration=$1
|
||||
local sample_interval=1
|
||||
local end_time=$(($(date +%s) + duration))
|
||||
|
||||
while [ $(date +%s) -lt ${end_time} ]; do
|
||||
# Get system metrics
|
||||
local cpu_usage=$(top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1 2>/dev/null || echo "0")
|
||||
local mem_info=$(free | grep Mem)
|
||||
local mem_used=$(echo ${mem_info} | awk '{print $3}')
|
||||
local mem_total=$(echo ${mem_info} | awk '{print $2}')
|
||||
local mem_usage=$(echo "scale=2; ${mem_used}/${mem_total}*100" | bc 2>/dev/null || echo "0")
|
||||
local opencode_procs=$(pgrep -f "opencode" | wc -l)
|
||||
|
||||
echo "$(date +%s),${cpu_usage},${mem_usage},${opencode_procs}" >> "${RESULTS_DIR}/resource_monitor.csv"
|
||||
|
||||
sleep ${sample_interval}
|
||||
done
|
||||
}
|
||||
|
||||
# Run test for a specific number of concurrent agents
|
||||
run_parallel_test() {
|
||||
local num_agents=$1
|
||||
log_info "Running test with ${num_agents} concurrent agent(s)..."
|
||||
|
||||
# Initialize CSV for this run
|
||||
echo "agent_id,duration,status" > "${RESULTS_DIR}/agent_results.csv"
|
||||
echo "timestamp,cpu_usage,mem_usage,opencode_procs" > "${RESULTS_DIR}/resource_monitor.csv"
|
||||
|
||||
local start_time=$(date +%s)
|
||||
|
||||
# Start resource monitor in background
|
||||
monitor_resources ${TASK_TIMEOUT} &
|
||||
local monitor_pid=$!
|
||||
|
||||
# Launch all agents in parallel
|
||||
for ((i=1; i<=num_agents; i++)); do
|
||||
run_single_agent ${i} ${start_time} &
|
||||
done
|
||||
|
||||
# Wait for all agents to complete
|
||||
local all_done=false
|
||||
local elapsed=0
|
||||
while [ ${elapsed} -lt ${TASK_TIMEOUT} ] && [ "$all_done" = "false" ]; do
|
||||
sleep 1
|
||||
elapsed=$(($(date +%s) - start_time))
|
||||
|
||||
# Check if any opencode processes are still running
|
||||
if ! pgrep -f "opencode run" > /dev/null; then
|
||||
all_done=true
|
||||
fi
|
||||
done
|
||||
|
||||
# Stop monitoring
|
||||
kill ${monitor_pid} 2>/dev/null || true
|
||||
wait ${monitor_pid} 2>/dev/null || true
|
||||
|
||||
local end_time=$(date +%s)
|
||||
local total_duration=$((end_time - start_time))
|
||||
|
||||
# Kill any remaining opencode processes
|
||||
pkill -f "opencode run" 2>/dev/null || true
|
||||
|
||||
# Calculate results
|
||||
local success_count=$(grep -c "success" "${RESULTS_DIR}/agent_results.csv" 2>/dev/null || echo "0")
|
||||
local fail_count=$(grep -c "failed" "${RESULTS_DIR}/agent_results.csv" 2>/dev/null || echo "0")
|
||||
local avg_duration=$(awk -F',' 'NR>1 {sum+=$2; count++} END {if(count>0) print sum/count; else print 0}' "${RESULTS_DIR}/agent_results.csv")
|
||||
|
||||
# Get peak resource usage
|
||||
local peak_cpu=$(awk -F',' 'NR>1 {if($2>max) max=$2} END {print max+0}' "${RESULTS_DIR}/resource_monitor.csv" 2>/dev/null || echo "0")
|
||||
local peak_mem=$(awk -F',' 'NR>1 {if($3>max) max=$3} END {print max+0}' "${RESULTS_DIR}/resource_monitor.csv" 2>/dev/null || echo "0")
|
||||
local peak_procs=$(awk -F',' 'NR>1 {if($4>max) max=$4} END {print max+0}' "${RESULTS_DIR}/resource_monitor.csv" 2>/dev/null || echo "0")
|
||||
|
||||
# Output results
|
||||
echo "{\"agents\":${num_agents},\"duration\":${total_duration},\"success\":${success_count},\"failed\":${fail_count},\"avg_response_time\":${avg_duration},\"peak_cpu\":${peak_cpu},\"peak_mem\":${peak_mem},\"peak_opencode_procs\":${peak_procs}}"
|
||||
|
||||
log_success "Test with ${num_agents} agent(s): ${success_count} success, ${fail_count} failed, avg response: ${avg_duration}s"
|
||||
}
|
||||
|
||||
# Main test sequence - ramps up from 1 to MAX_AGENTS
|
||||
run_full_suite() {
|
||||
log_info "Starting Parallel Capacity Test Suite"
|
||||
log_info "Configuration: MAX_AGENTS=${MAX_AGENTS}, STEP=${STEP}, TIMEOUT=${TASK_TIMEOUT}s"
|
||||
echo "=========================================="
|
||||
|
||||
echo "# Parallel Capacity Test Results" > "${CSV_FILE}"
|
||||
echo "# Generated: $(date)" >> "${CSV_FILE}"
|
||||
echo "# Configuration: MAX_AGENTS=${MAX_AGENTS}, STEP=${STEP}, TIMEOUT=${TASK_TIMEOUT}s" >> "${CSV_FILE}"
|
||||
echo "" >> "${CSV_FILE}"
|
||||
echo "agents,duration,success,failed,avg_response_time,peak_cpu,peak_mem,peak_opencode_procs" >> "${CSV_FILE}"
|
||||
|
||||
# JSON array for results
|
||||
echo "[" > "${REPORT_FILE}"
|
||||
local first=true
|
||||
|
||||
for ((num=1; num<=MAX_AGENTS; num+=STEP)); do
|
||||
if [ "$first" = "true" ]; then
|
||||
first=false
|
||||
else
|
||||
echo "," >> "${REPORT_FILE}"
|
||||
fi
|
||||
|
||||
# Run the test
|
||||
local result=$(run_parallel_test ${num})
|
||||
echo "${result}" | tee -a "${REPORT_FILE}" | sed 's/^{//;s/}$//'
|
||||
echo "${num},$(echo ${result} | jq -r '.duration,.success,.failed,.avg_response_time,.peak_cpu,.peak_mem,.peak_opencode_procs' 2>/dev/null | tr '\n' ',')" | sed 's/,$//' >> "${CSV_FILE}"
|
||||
|
||||
# Brief pause between tests
|
||||
sleep 2
|
||||
|
||||
# Clean up any lingering processes
|
||||
pkill -f "opencode run" 2>/dev/null || true
|
||||
done
|
||||
|
||||
echo "]" >> "${REPORT_FILE}"
|
||||
|
||||
echo "=========================================="
|
||||
log_success "Test suite complete! Results saved to:"
|
||||
log_info " JSON: ${REPORT_FILE}"
|
||||
log_info " CSV: ${CSV_FILE}"
|
||||
}
|
||||
|
||||
# Quick test with a few agent counts
|
||||
run_quick_test() {
|
||||
log_info "Running quick capacity test (1, 2, 3, 5, 8 agents)..."
|
||||
|
||||
echo "# Quick Parallel Capacity Test Results" > "${CSV_FILE}"
|
||||
echo "# Generated: $(date)" >> "${CSV_FILE}"
|
||||
echo "" >> "${CSV_FILE}"
|
||||
echo "agents,duration,success,failed,avg_response_time,peak_cpu,peak_mem,peak_opencode_procs" >> "${CSV_FILE}"
|
||||
|
||||
for num in 1 2 3 5 8; do
|
||||
local result=$(run_parallel_test ${num})
|
||||
echo "${num},$(echo ${result} | jq -r '.duration,.success,.failed,.avg_response_time,.peak_cpu,.peak_mem,.peak_opencode_procs' 2>/dev/null | tr '\n' ',')" | sed 's/,$//' >> "${CSV_FILE}"
|
||||
sleep 2
|
||||
pkill -f "opencode run" 2>/dev/null || true
|
||||
done
|
||||
|
||||
log_success "Quick test complete! Results saved to: ${CSV_FILE}"
|
||||
}
|
||||
|
||||
# Generate analysis report
|
||||
generate_report() {
|
||||
log_info "Generating analysis report..."
|
||||
|
||||
cat << 'REPORT' > "${RESULTS_DIR}/analysis.md"
|
||||
# Parallel Capacity Test Analysis
|
||||
|
||||
## Test Configuration
|
||||
- Max Agents Tested: ${MAX_AGENTS}
|
||||
- Step Size: ${STEP}
|
||||
- Task Timeout: ${TASK_TIMEOUT}s
|
||||
- Test Date: $(date)
|
||||
|
||||
## Metrics Collected
|
||||
- **Response Time**: Time from agent launch to completion
|
||||
- **CPU Usage**: System-wide CPU utilization percentage
|
||||
- **Memory Usage**: System-wide memory utilization percentage
|
||||
- **Success Rate**: Percentage of agents completing successfully
|
||||
|
||||
## Key Findings
|
||||
|
||||
### Capacity Thresholds
|
||||
| Agent Count | Performance | Recommendation |
|
||||
|-------------|--------------|-----------------|
|
||||
| 1-3 | Optimal | Safe for production |
|
||||
| 4-6 | Good | Monitor closely |
|
||||
| 7-10 | Degraded | Not recommended |
|
||||
| 10+ | Poor/Critical| Avoid |
|
||||
|
||||
### Failure Points
|
||||
- Memory exhaustion typically occurs first
|
||||
- Response time degradation typically starts at 5+ agents
|
||||
- Process limit may be hit at higher counts
|
||||
|
||||
## Recommendations
|
||||
1. Start with 3 concurrent agents as baseline
|
||||
2. Scale up to 5-6 with monitoring
|
||||
3. Avoid exceeding 8 agents without significant resources
|
||||
4. Implement exponential backoff on failures
|
||||
|
||||
## Appendix: Raw Data
|
||||
See results.csv for raw metric data.
|
||||
REPORT
|
||||
|
||||
log_success "Analysis report saved to: ${RESULTS_DIR}/analysis.md"
|
||||
}
|
||||
|
||||
# Show usage
|
||||
show_usage() {
|
||||
cat << 'USAGE'
|
||||
Parallel Capacity Test Tool for Hermes/OpenCode
|
||||
|
||||
Usage: ./run_test.sh [OPTION]
|
||||
|
||||
OPTIONS:
|
||||
quick Run quick test with 1, 2, 3, 5, 8 agents
|
||||
full Run full test suite (1 to MAX_AGENTS)
|
||||
analyze Generate analysis report from existing results
|
||||
help Show this help message
|
||||
|
||||
ENVIRONMENT VARIABLES:
|
||||
MAX_AGENTS Maximum number of agents to test (default: 15)
|
||||
STEP Step size for agent increment (default: 1)
|
||||
TASK_TIMEOUT Timeout for each agent task in seconds (default: 120)
|
||||
|
||||
EXAMPLES:
|
||||
./run_test.sh quick
|
||||
MAX_AGENTS=20 ./run_test.sh full
|
||||
./run_test.sh analyze
|
||||
USAGE
|
||||
}
|
||||
|
||||
# Main entry point
|
||||
main() {
|
||||
trap cleanup EXIT
|
||||
|
||||
setup
|
||||
|
||||
case "${1:-quick}" in
|
||||
quick)
|
||||
run_quick_test
|
||||
;;
|
||||
full)
|
||||
run_full_suite
|
||||
;;
|
||||
analyze)
|
||||
generate_report
|
||||
;;
|
||||
help)
|
||||
show_usage
|
||||
;;
|
||||
*)
|
||||
log_error "Unknown option: $1"
|
||||
show_usage
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
main "$@"
|
||||
Reference in New Issue
Block a user