apache / apache/maka

refactor(runtime): group flat 198-file src/ into logical subdirectories

Open
#3,912 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.