apache / apache/maka

refactor(runtime): decompose session-manager.ts god-object (6445 lines, 40+ exports)

Open
#3,908 1 comment 0 reactions 1 assignee Claimed by @spuru9 View on GitHub
Dominant language
TypeScript
Stars
5.4k
Forks
502
Avg merge
1d 2h
Merged PRs (30d)
716

Description

## Summary

`packages/runtime/src/session-manager.ts` is 6,445 lines with 40+ exported interfaces, mixing session lifecycle, child agent spawning, agent graph intent, conversation copy, configuration transitions, plan state, and recovery. This god-object makes every change touch one file and makes ownership unclear.

## Evidence

- `packages/runtime/src/session-manager.ts:1-6775` — exports 8+ categories of types including `SpawnChildAgentInput`, `ProvisionAgentGraphOperatorInput`, `PlanSafeBoundaryContinuationInput`, `SessionConfigurationTransitionRequest`, `CompactSessionInput`
- `runtime-host` already consumes these via named sub-exports (`@maka/runtime/session-manager`); splitting internally would not break the public API
- Related files that already exist but are underused: `session-projection-helpers.ts`, `session-recap.ts`, `session-title.ts`, `session-trace-projection.ts`

## Proposed Decomposition

Extract along existing seams into separate modules:
1. **`session-manager.ts`** — session CRUD, lifecycle, and configuration management
2. **`child-agent-manager.ts`** — child agent spawning, graph intent, and agent graph coordination
3. **`session-recovery.ts`** — recovery, continuation authority, and history repair
4. **`session-conversation.ts`** — conversation copy and transcript operations

Each extracted module would be consumed through the same barrel export path, preserving backward compatibility.

## Acceptance Criteria

- [ ] `session-manager.ts` is under 2,000 lines
- [ ] Each extracted module has a clear single responsibility
- [ ] All existing tests pass without modification
- [ ] Public API surface (`@maka/runtime/session-manager`) is unchanged
- [ ] No new cross-module cycles introduced

## Labels

refactor, help wanted

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.