From fb402d088aad5051ce0e0ed6aec13592b802a31b Mon Sep 17 00:00:00 2001 From: ZxlDragonDoctor <152901610+ZxlDragonDoctor@users.noreply.github.com> Date: Thu, 10 Sep 2026 19:22:10 +0800 Subject: [PATCH] docs(runtime): document declared subpaths and Runtime Host composition The README advertised a package-root barrel that package.json does not export, and pointed composition at the Desktop main process instead of the shared Runtime Host composition. Addresses #5141 --- packages/runtime/README.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/packages/runtime/README.md b/packages/runtime/README.md index f64672841e..13d77bd945 100644 --- a/packages/runtime/README.md +++ b/packages/runtime/README.md @@ -23,23 +23,31 @@ ## Public seam -The package root barrel and the subpaths declared in `package.json` are supported public APIs. Do not import undeclared internal source paths from another package. The main integration points are: +Only the **subpaths declared in `package.json` `exports`** are supported public APIs. There is **no package-root barrel**: `import('@maka/runtime')` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`. Do not import undeclared internal source paths from another package. -- `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. +Useful entry points and import examples: -Desktop composition lives in `apps/desktop/src/main/main.ts`. Other clients execute Maka through Runtime Host rather than composing Runtime directly. +- `SessionManager` and `BackendRegistry` — `@maka/runtime/session-manager` + ```ts + import { SessionManager, BackendRegistry } from "@maka/runtime/session-manager"; + ``` +- `AiSdkBackend` — `@maka/runtime/ai-sdk-backend` + ```ts + import { AiSdkBackend } from "@maka/runtime/ai-sdk-backend"; + ``` + `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 (`@maka/runtime/sandbox` and related declared subpaths). +- `buildBuiltinTools()` and the workspace executor interfaces (`@maka/runtime/builtin-tools`, `@maka/runtime/shell-tools`) for tool composition. +- `RuntimeKernel`, runtime events, projections, and recovery helpers (`@maka/runtime/runtime-kernel` and related declared subpaths) for execution lifecycle. + +Shared execution composition (where `BackendRegistry` and `SessionManager` are constructed) lives in `packages/runtime-host/src/server/execution-composition.ts`. Other clients execute Maka through Runtime Host rather than composing Runtime directly. The Desktop product shell is one host among those clients; do not treat `apps/desktop/src/main/main.ts` as the Runtime composition source of truth. ## 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 the root barrel or a declared `package.json` subpath rather than importing internal files from another package. +- Expose supported package APIs only through a declared `package.json` subpath. Do not add or rely on a package-root barrel unless `exports` gains a `"."` entry. - 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`.