@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.