| # `@maka/runtime` |
| |
| `@maka/runtime` is Maka's pure-Node agent runtime. It owns model/backend execution, session sandbox-boundary control flow, event projection, context handling, recovery, and sandbox-aware workspace execution. Product shells compose it; they do not reimplement its loop. |
| |
| ## Public seam |
| |
| The package root is the supported public API. The sole subpath export is a |
| test-only observation reader and is not a product integration seam. Do not |
| import internal source paths from another package. The main integration points are: |
| |
| - `SessionManager` for session and turn orchestration. |
| - `BackendRegistry` and `AgentBackend` for backend selection. |
| - `AiSdkBackend`, `PiAgentBackend`, and `FakeBackend` for the existing backend implementations. |
| - Session execution-boundary APIs for managed sandbox expansion and explicit bypass. |
| - `buildBuiltinTools()` and the workspace executor interfaces for tool composition. |
| - `RuntimeRunner`, runtime events, projections, and recovery helpers for invocation lifecycle. |
| |
| Desktop composition lives in `apps/desktop/src/main/main.ts`. Headless composition lives in `packages/headless`; it must supply real executor/backend wiring explicitly. |
| |
| ## Extension rules |
| |
| - Add backend behavior behind `AgentBackend` and register it through the existing registry. |
| - Add tools through the builtin/tool composition seams; keep filesystem and shell effects behind `WorkspaceExecutor`. |
| - Put shared pure contracts in `packages/core` and durable JSONL state in `packages/storage`. |
| - Expose supported package APIs through the root barrel rather than importing internal files from another package. |
| - Keep provider credentials and Electron IPC outside this package. The product shell resolves credentials and passes only the dependencies required for execution. |
| |
| For the system-level model and code-reading map, start with the root `ARCHITECTURE.md`. Sandbox-specific contracts live in `src/sandbox/README.md`. |
