mikkel/homelab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(01): complete session-process-foundation phase

Browse source 
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Mikkel Georgsen 2026-02-04 18:32:54 +00:00
parent d878931e79
commit 03aaf64cff
4 changed files with 204 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
.planning/REQUIREMENTS.md
View file

@ -14,10 +14,10 @@
### Session Management
- [ ] **SESS-01**: Path-based sessions stored in `~/telegram/sessions/<name>/` with own Claude Code history
- [ ] **SESS-02**: `/session <name>` command switches active session
- [x] **SESS-01**: Path-based sessions stored in `~/telegram/sessions/<name>/` with own Claude Code history
- [x] **SESS-02**: `/session <name>` command switches active session
- [ ] **SESS-03**: `/sessions` command lists all sessions sorted by last activity
- [ ] **SESS-04**: `/new <name>` creates new session; first-ever message auto-creates default session
- [x] **SESS-04**: `/new <name>` creates new session; first-ever message auto-creates default session
### Lifecycle
@ -35,8 +35,8 @@
### Infrastructure
- [ ] **INFRA-01**: Runs as systemd user service alongside existing bot
- [ ] **INFRA-02**: Async subprocess management via asyncio (no PIPE deadlocks)
- [ ] **INFRA-03**: Concurrent stdout/stderr draining prevents buffer overflow
- [x] **INFRA-02**: Async subprocess management via asyncio (no PIPE deadlocks)
- [x] **INFRA-03**: Concurrent stdout/stderr draining prevents buffer overflow
## v2 Requirements
@ -71,10 +71,10 @@
| MSG-02 | Phase 2 | Pending |
| MSG-03 | Phase 2 | Pending |
| MSG-04 | Phase 2 | Pending |
| SESS-01 | Phase 1 | Pending |
| SESS-02 | Phase 1 | Pending |
| SESS-01 | Phase 1 | Complete |
| SESS-02 | Phase 1 | Complete |
| SESS-03 | Phase 3 | Pending |
| SESS-04 | Phase 1 | Pending |
| SESS-04 | Phase 1 | Complete |
| LIFE-01 | Phase 3 | Pending |
| LIFE-02 | Phase 3 | Pending |
| LIFE-03 | Phase 3 | Pending |
@ -83,8 +83,8 @@
| OUT-02 | Phase 4 | Pending |
| OUT-03 | Phase 4 | Pending |
| INFRA-01 | Phase 2 | Pending |
| INFRA-02 | Phase 1 | Pending |
| INFRA-03 | Phase 1 | Pending |
| INFRA-02 | Phase 1 | Complete |
| INFRA-03 | Phase 1 | Complete |
**Coverage:**
- v1 requirements: 18 total

10
.planning/ROADMAP.md
View file

@ -12,7 +12,7 @@ This project transforms Telegram into a mobile interface for Claude Code, enabli
Decimal phases appear between their surrounding integers in numeric order.
- [ ] **Phase 1: Session & Process Foundation** - Multi-session filesystem structure with subprocess management
- [x] **Phase 1: Session & Process Foundation** - Multi-session filesystem structure with subprocess management
- [ ] **Phase 2: Telegram Integration** - Core messaging loop with file handling and typing indicators
- [ ] **Phase 3: Lifecycle Management** - Idle timeout, suspend/resume, and graceful cleanup
- [ ] **Phase 4: Output Modes** - Advanced output control for verbose and smart modes
@ -32,9 +32,9 @@ Decimal phases appear between their surrounding integers in numeric order.
**Plans:** 3 plans
Plans:
- [ ] 01-01-PLAN.md -- Session manager module and persona library
- [ ] 01-02-PLAN.md -- Claude Code subprocess engine
- [ ] 01-03-PLAN.md -- Bot command integration (/new, /session, message routing)
- [x] 01-01-PLAN.md -- Session manager module and persona library
- [x] 01-02-PLAN.md -- Claude Code subprocess engine
- [x] 01-03-PLAN.md -- Bot command integration (/new, /session, message routing)
### Phase 2: Telegram Integration
**Goal**: Messages flow bidirectionally between Telegram and Claude with file support and status feedback
@ -87,7 +87,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Session & Process Foundation | 0/3 | Planned | - |
| 1. Session & Process Foundation | 3/3 | Complete | 2026-02-04 |
| 2. Telegram Integration | 0/TBD | Not started | - |
| 3. Lifecycle Management | 0/TBD | Not started | - |
| 4. Output Modes | 0/TBD | Not started | - |

37
.planning/STATE.md
View file

@ -10,28 +10,28 @@ See: .planning/PROJECT.md (updated 2026-02-04)
## Current Position
Phase: 1 of 4 (Session & Process Foundation)
Plan: 01-01 complete (2 of 3 plans completed)
Status: In progress
Last activity: 2026-02-04 — Completed 01-01-PLAN.md (SessionManager + Persona library)
Plan: 01-03 complete (3 of 3 plans completed)
Status: Phase 1 complete
Last activity: 2026-02-04 — Completed 01-03-PLAN.md (Bot command integration)
Progress: [██░░░░░░░░] 20%
Progress: [███░░░░░░░░░░░░] 25%
## Performance Metrics
**Velocity:**
- Total plans completed: 2
- Average duration: 6 min
- Total execution time: 0.20 hours
- Total plans completed: 3
- Average duration: 10 min
- Total execution time: 0.50 hours
**By Phase:**
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| 1 | 2 | 12min | 6min |
| 1 | 3 | 27min | 9min |
**Recent Trend:**
- Last 5 plans: 01-01 (3min), 01-02 (9min)
- Trend: -
- Last 3 plans: 01-01 (3min), 01-02 (9min), 01-03 (15min)
- Trend: Increasing complexity (more orchestrator fixes)
*Updated after each plan completion*
@ -51,6 +51,8 @@ Recent decisions affecting current work:
- Asyncio.gather for concurrent stream reading: Prevents pipe deadlock (01-02)
- Fresh process per turn: Spawn new `claude -p` invocation for Phase 1 simplicity (01-02)
- Callback architecture: Decouple subprocess from session management via on_output/on_error/on_complete/on_status (01-02)
- Sibling imports over package imports: Avoids shadowing pip telegram package (01-03)
- Archive sessions with tar+pigz: Compression + cleanup to sessions_archive/ (01-03)
### Pending Todos
@ -58,16 +60,25 @@ None yet.
### Blockers/Concerns
**Phase 1 (Session & Process Foundation):**
**Phase 1 (Session & Process Foundation) — COMPLETE**
- ~~Claude Code CLI --resume behavior with pipes vs PTY unknown~~ — RESOLVED: Research confirms pipes + stream-json is correct approach
- ~~Output format for tool calls not documented~~ — RESOLVED: stream-json format documented and implemented
**Phase 2 (Persistent Processes) — BLOCKER:**
- **Non-persistent process model:** Current implementation spawns fresh `claude -p` per turn (~1s overhead each)
- Design goal was persistent processes that suspend when switching sessions
- This gap affects response latency and user experience
- Must be addressed before Phase 3 integration
- Requires refactoring ClaudeSubprocess to lifecycle-manage process instances
**Phase 3 (Telegram Integration):**
- Message batching strategy needs validation against actual Claude output patterns
- Optimal chunk split points require experimentation
- Streaming responses / typing indicators needed for UX during long API waits
## Session Continuity
Last session: 2026-02-04T17:34:10Z
Stopped at: Completed 01-01-PLAN.md (SessionManager + Persona library)
Last session: 2026-02-04T18:00:00Z
Stopped at: Completed 01-03-PLAN.md (Bot command integration)
Resume file: None
Next: Phase 2 ready (persistent process model needed)

165
.planning/phases/01-session-process-foundation/01-03-SUMMARY.md Normal file
View file

@ -0,0 +1,165 @@
---
phase: 01-session-process-foundation
plan: 03
subsystem: infra
tags: [telegram-bot, integration, commands, session-management]
requires:
- plan: 01-01
provides: SessionManager class, persona library
- plan: 01-02
provides: ClaudeSubprocess class, stream-json parsing
provides:
- /new and /session commands in Telegram bot
- /archive command for session cleanup
- Message routing to Claude Code subprocess
- Callback-based response delivery to Telegram
- Session-aware bot handler
affects: [telegram-bot, phase-02-persistent-processes]
tech-stack:
added: []
patterns:
- "Session-aware message routing in Telegram handlers"
- "Async callback factory for subprocess → Telegram bridge"
- "Callback-based inter-component communication"
key-files:
created: []
modified:
- telegram/bot.py
key-decisions:
- "Sibling imports instead of package imports (avoids telegram namespace collision with pip package)"
- "Fresh claude -p process per message turn (Phase 1 simplicity, contradicts persistent process goal)"
- "Archive sessions with tar+pigz to sessions_archive/"
- "Block=False on message handler for non-blocking execution"
patterns-established:
- "make_callbacks factory binds bot + chat_id for subprocess callbacks"
- "Session metadata read on-demand from disk"
- "Personas loaded from disk without caching"
duration: 15min
completed: 2026-02-04
---
# Phase 01 Plan 03: Bot Command Integration Summary
**Integrated SessionManager and ClaudeSubprocess into Telegram bot with /new, /session, /archive commands and session-aware message routing**
## Performance
- Duration: 15 min
- Tasks: 2 (1 auto, 1 human-verify)
- Files modified: 1
- Commands added: 3
- Commits: 1 task + 7 orchestrator fixes
## Accomplishments
### Primary Features
- Added `/new` command to create and activate new sessions
- Added `/session` command to list and switch between sessions
- Added `/archive` command to compress and cleanup sessions
- Session-aware message routing:
- No active session → prompts user to create or select
- Active session → routes message to Claude subprocess
- Callback-based response delivery from subprocess to Telegram
- All existing bot commands preserved and working
### Quality & Debugging
- Non-blocking message handler (block=False) prevents bot freezes
- [TIMING] profiler instrumentation added for response latency debugging
- Async callback factory pattern decouples subprocess from session manager
- Proper SIGTERM signal handling (subprocess completion, not crashes)
## Task Completion
| Task | Name | Status | Commit |
|------|------|--------|--------|
| 1 | Add /new and /session commands | Complete | 3a62e01 |
| 2 | Human verify session flow | Complete | approved |
## Orchestrator Fixes Applied
| Commit | Type | Description |
|--------|------|-------------|
| d08f352 | fix | Import collision: telegram/ shadowed pip telegram package |
| 3cc97ad | fix | SIGTERM not treated as crash + async callbacks in crash handler |
| a27ac01 | feat | Add /archive command for session cleanup |
| faab47a | refactor | Restructure personas (default, homelab, brainstorm, planner, research) |
| 3fec4ed | fix | Update persona models to use aliases not versions |
| 2302b75 | fix | Fix persona settings nested under "settings" object |
| (pending) | perf | [TIMING] profiler instrumentation for response latency |
## Decisions Made
1. **Import Strategy:** Sibling imports (`from session_manager import`) instead of package imports to avoid shadowing the pip `telegram` package
2. **Process Lifecycle:** Fresh `claude -p` process per message turn for Phase 1 simplicity (not persistent)
3. **Session Activation:** Creating a session does not activate it; must use /session command (prevents accidental switches)
4. **Archive Format:** tar+pigz compression for session archives stored in `sessions_archive/`
## Known Gaps & Deviations
### Gap: Non-persistent Subprocess Model
The implementation spawns a fresh `claude -p` process per message turn. This contradicts the design decision:
- **Original goal:** "Switching sessions suspends (doesn't kill) current process — stays alive"
- **Current behavior:** Fresh process each turn
- **Impact:**
- ~1s CLI startup overhead per message
- No session continuity without --continue flag
- Every message is a cold-start
- No streaming responses or typing indicators
**Status:** Known Phase 1 simplification. Should be addressed in Phase 2 with persistent process model.
### Auto-fixed Issues (Not in Original Plan)
1. **Import Collision** (d08f352)
- telegram/ directory __init__.py shadowed pip telegram package
- Fixed: Restructured imports to use sibling module pattern
2. **SIGTERM Handling** (3cc97ad)
- SIGTERM interpreted as crash during service restarts
- Fixed: Properly distinguished between SIGTERM (clean exit) and actual crashes
3. **Persona Settings Bug** (2302b75)
- Persona settings nested under "settings" object, not being read
- Fixed: Flattened settings structure in persona models
4. **Hardcoded Model Versions** (3fec4ed)
- Model versions from training data instead of using aliases
- Fixed: Updated to use model aliases (default: claude-opus-4-5-20251101)
## Deviations Summary
**Auto-fixed (Rule 2 - Critical):** 4 issues fixed automatically (import collision, signal handling, persona settings, hardcoded versions)
**Planned Gaps:** 1 known gap documented (non-persistent processes → Phase 2)
## Issues Encountered
- Subprocess model flag not being passed to Claude (persona settings nesting)
- Response latency ~10s (API wait + no streaming feedback)
- Fresh process overhead ~1s per message turn
## Next Phase Readiness
**Status:** Phase 1 Complete, Phase 2 Ready (with known gaps documented)
**Readiness assessment:**
- Session management: ✓ Complete
- Subprocess integration: ✓ Complete
- Bot commands: ✓ Complete
- Message routing: ✓ Complete
**Blockers for Phase 2:**
- Persistent process model (replace one-shot `claude -p`)
- Streaming responses needed for UX (typing indicators)
- Message batching strategy for long responses
- Response latency profiling and optimization
---
*Phase 01 Plan 03 | Completed 2026-02-04 | Duration 15 min*