refactor(runtime): group flat 198-file src/ into logical subdirectories
- Dominant language
- TypeScript
- Stars
- 5.4k
- Forks
- 502
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 715
Description
## Summary
`packages/runtime/src/` has 198 files at the root level with no subdirectory decomposition beyond `__tests__/`, `bots/`, `filesystem-worker/`, `network/`, `sandbox/`, `system-prompt/`, `telemetry/`, and `test-only/`. This makes subsystem boundaries implicit and navigation difficult.
## Evidence
- `packages/runtime/src/` — 198 entries at root
- Related file clusters that should be grouped:
- 3 agent-run files: `agent-run.ts`, `agent-run-inspect.ts`, `agent-run-recovery.ts`
- 5 session files: `session-manager.ts`, `session-projection-helpers.ts`, `session-recap.ts`, `session-title.ts`, `session-trace-projection.ts`
- 8 skills files: `skills.ts`, `skills-agent-tools.ts`, `skills-context.ts`, `skills-discovery.ts`, `skills-governance.ts`, `skills-metadata.ts`, `skills-starter.ts`, `skills-state.ts`
- 5 history-compact files: `history-compaction.ts`, `history-compact-summarizer.ts`, `ai-sdk-compaction.ts`, `compaction-budget.ts`, `compaction-event.ts`
- 6+ goal files: `goal-tools.ts`, `goal-continuation.ts`, `goal-evaluator.ts`, `goal-state.ts`
- 6+ shell files: `shell-detect.ts`, `shell-exec.ts`, `shell-run-manager.ts`, `shell-tools.ts`
## Proposed Solution
Group related files into subdirectories:
- `agent-run/` — agent run lifecycle and inspection
- `session/` — session management and projection
- `skills/` — skills system
- `history-compact/` — context compaction
- `goal/` — goal evaluation and continuation
- `shell/` — shell detection and execution
Barrel exports (`index.ts`) in each subdirectory would preserve backward compatibility.
## Acceptance Criteria
- [ ] Related files are grouped into logical subdirectories
- [ ] Barrel exports preserve all existing public API paths
- [ ] All imports across the codebase are updated
- [ ] All tests pass
- [ ] No new cross-directory cycles
## Labels
refactor, help wanted
Contributor guide
Research direction
Start in packages/runtime/src/ and map the listed agent-run, session, skills, history-compaction, goal, and shell files to their imports and existing public exports. Review how current subdirectories expose files before creating the proposed barrel exports. Done means related files are grouped, imports and public paths still work, all tests pass, and no new cross-directory cycles appear.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend, developer-experience
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100