From 4776e8f1908149505a01a2e6c247e55642b146a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=86=E9=80=8A?= Date: Fri, 11 Sep 2026 23:48:37 +0800 Subject: [PATCH 1/2] docs(runtime): document subpath-only public API and shared composition entry - State that the public API is the declared package.json exports subpaths; the package root is not exported (import('@maka/runtime') fails with ERR_PACKAGE_PATH_NOT_EXPORTED) - Add explicit subpath import examples for SessionManager, BackendRegistry, AiSdkBackend, and buildBuiltinTools - Point contributors to the shared Runtime Host execution composition instead of the stale apps/desktop/src/main/main.ts entry Fixes #5141 --- packages/runtime/README.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/packages/runtime/README.md b/packages/runtime/README.md index f64672841e..d488ecc13a 100644 --- a/packages/runtime/README.md +++ b/packages/runtime/README.md @@ -23,7 +23,15 @@ ## 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: +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: + +```ts +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. @@ -32,14 +40,14 @@ The package root barrel and the subpaths declared in `package.json` are supporte - `buildBuiltinTools()` and the workspace executor interfaces for tool composition. - `RuntimeKernel`, runtime events, projections, and recovery helpers for execution lifecycle. -Desktop composition lives in `apps/desktop/src/main/main.ts`. Other clients execute Maka through Runtime Host rather than composing Runtime directly. +Shared execution composition — where `BackendRegistry` and `SessionManager` are constructed — lives in the Runtime Host at [`packages/runtime-host/src/server/execution-composition.ts`](../../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 the root barrel or a declared `package.json` subpath rather than importing internal files from another package. +- 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`. From 042774410cf9d53937dd73f89655a8b4d0c53537 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=86=E9=80=8A?= Date: Sat, 12 Sep 2026 09:03:23 +0800 Subject: [PATCH 2/2] docs(runtime): simplify composition link to the same-packages relative path Review feedback on #5200: a reference into a sibling package uses one '../' hop (packages/runtime/ -> packages/runtime-host/...), matching the convention in packages/eval's README. --- packages/runtime/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/runtime/README.md b/packages/runtime/README.md index d488ecc13a..cd3bc72a32 100644 --- a/packages/runtime/README.md +++ b/packages/runtime/README.md @@ -40,7 +40,7 @@ The main integration points are: - `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`](../../packages/runtime-host/src/server/execution-composition.ts). Clients, including Desktop, execute Maka through Runtime Host rather than composing Runtime directly. +Shared execution composition — where `BackendRegistry` and `SessionManager` are constructed — lives in the Runtime Host at [`packages/runtime-host/src/server/execution-composition.ts`](../runtime-host/src/server/execution-composition.ts). Clients, including Desktop, execute Maka through Runtime Host rather than composing Runtime directly. ## Extension rules