Google GitGoogle Git
Sign in
apache/maka/HEAD/./packages/runtime
tree: e14575cd6c37009824081ffd241429ce52356ea1
  1. resources/
  2. scripts/
  3. src/
  4. package.json
  5. README.md
  6. tsconfig.json
packages/runtime/README.md

@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 supported public API is the set of subpaths declared in the exports map of package.json. The package root is not exported: import('@maka/runtime') fails with ERR_PACKAGE_PATH_NOT_EXPORTED. Do not import undeclared internal source paths from another package. For example:

import { SessionManager, BackendRegistry } from '@maka/runtime/session-manager';
import { AiSdkBackend } from '@maka/runtime/ai-sdk-backend';
import { buildBuiltinTools } from '@maka/runtime/builtin-tools';

The main integration points are:

  • SessionManager for session and turn orchestration.
  • BackendRegistry and AgentBackend for backend selection.
  • AiSdkBackend for the shipped backend implementation. FakeBackend is test-only: it lives under test-only/, is exported as @maka/runtime/test-only/fake-backend, and release packaging drops that directory, so no production module may import it. Tests and the Desktop E2E run reach it through the composition's primaryBackendFactory seam.
  • Session execution-boundary APIs for managed sandbox expansion and explicit bypass.
  • buildBuiltinTools() and the workspace executor interfaces for tool composition.
  • RuntimeKernel, runtime events, projections, and recovery helpers for execution lifecycle.

Shared execution composition — where BackendRegistry and SessionManager are constructed — lives in the Runtime Host at packages/runtime-host/src/server/execution-composition.ts. Clients, including Desktop, execute Maka through Runtime Host rather than composing Runtime directly.

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 interactive Runtime state in the SQLite control plane owned by packages/storage.
  • Expose supported package APIs through a declared package.json exports subpath 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.