feat: Long-running session mode for deep work dispatch

[rsdrahat]

Problem

NanoClaw's container model is single-shot: agent wakes, processes messages, responds, and idles/dies. This works well for reactive tasks (quick questions, scheduled briefings, calendar management) but falls short for:

• Deep coding sessions — multi-step refactors, debugging with 20+ file reads, iterative test-fix cycles
• Complex research — rabbit-hole exploration that requires building progressive understanding
• Document collaboration — 15 rounds of revision on a pitch deck or strategy doc

The fundamental limitation is that each invocation starts with a cold context. Conversation history replay (#2 from this repo's approach) bridges ~85-90% of the gap for planning/briefing tasks but only ~40-50% for deep coding, because replayed history lacks the reasoning chain, tool call results, and progressive context building of a continuous session.

Proposed Solution

Add a dispatch mechanism where the orchestrator can choose between execution modes based on task type:

Execution Modes

Mode	When	How
Container (current)	Quick reactive tasks, scheduled tasks	Existing container runner
Persistent session	Deep coding, research, multi-step work	Long-lived Claude Code process on host

Architecture

User (Telegram) → NanoClaw Orchestrator → Mode Router
                                            ├── Container Runner (existing)
                                            └── Session Runner (new)
                                                 ├── Spawns claude-code CLI process
                                                 ├── Pipes messages via stdin
                                                 ├── Streams responses back
                                                 └── Maintains session until explicitly ended

Session Runner Behavior

1. User triggers deep work mode (explicit command like /deep or agent detects complex task)
2. Orchestrator spawns a claude CLI process with the topic's working directory and CLAUDE.md
3. Messages from Telegram are piped into the session as follow-up prompts
4. Responses stream back to Telegram (with intermediate progress updates per No intermediate feedback during long-running agent sessions #1440)
5. Session stays alive until: user says "done", idle timeout (configurable), or explicit /end
6. On session end, key outcomes are summarized and written to the topic's state files

Key Design Decisions

• Security model: Persistent sessions run on the host, not in containers. This means less isolation but access to the full filesystem (which is what deep coding needs). Could optionally run in a persistent container with mounted volumes.
• Topic binding: Each topic can have at most one active persistent session. New messages in that topic go to the session, not a new container.
• Hybrid: The orchestrator decides which mode to use. Quick messages still go through containers even if a session exists (or queue for the session — TBD).
• Resource management: Max concurrent sessions, idle timeout, memory monitoring.

Related Issues

• RFC: CLI Channel for Claude Code Integration #642 — RFC: CLI Channel for Claude Code Integration (bidirectional CLI↔NanoClaw, complementary)
• Research: MemStack — persistent memory and session context for Claude agents #1495 — MemStack persistent memory research (session handoff patterns)
• No intermediate feedback during long-running agent sessions #1440 — No intermediate feedback during long-running sessions (progress updates needed for persistent mode too)
• Agent memory system redesign #1356 — Agent memory system redesign (persistent sessions would benefit from better memory)

Alternatives Considered

1. Just increase container timeout — doesn't help; the issue isn't timeout but context loss between invocations
2. Run separate Claude Code sessions manually — works but breaks the single-interface promise
3. Replay full tool call history — prohibitively expensive context-wise and still loses reasoning chain

Implementation Sketch

1. New SessionRunner class alongside ContainerRunner
2. Mode selection logic in processGroupMessages (heuristic or explicit trigger)
3. Bidirectional message piping (Telegram ↔ Claude CLI stdin/stdout)
4. Session lifecycle management (create, pipe, idle-timeout, end, summarize)
5. Progress update integration (No intermediate feedback during long-running agent sessions #1440)

🤖 Generated with Claude Code