refactor: consolidate public APIs and computer-use scripts

[jackwener]

Summary

Consolidates the duplicated package and script entry surfaces:

• reduces @maka/core exports from 104 to the root product API plus the non-overlapping @maka/core/node adapter;
• reduces @maka/runtime exports from 54 to the root product API plus its existing test-only observation helper;
• migrates product and test consumers away from per-file package subpaths;
• replaces 17 Computer Use npm entrypoints with npm run e2e:computer-use -- <command> and one canonical dispatcher;
• keeps the core root browser-safe by replacing eager Node hashing/deep-comparison dependencies with platform-neutral implementations;
• adds package-export and dispatcher contract tests.

Verification

• npm run build:test
• npm run typecheck
• npm run lint
• npm run format:check
• npm --workspace @maka/desktop run build:renderer
• npm --workspace @maka/core test — 815 passed
• npm --workspace @maka/ui run test:dist — 260 passed
• npm --workspace @maka/desktop run test:dist — 1131 passed
• targeted Runtime boundary/recovery tests — 35 passed
• package API and Computer Use dispatcher contract tests — 4 passed

The full npm test run exposed one unrelated existing Storage failure: importing the Storage root emits the Node node:sqlite ExperimentalWarning through existing static imports in session-bundle-policy.ts / operational-state-backup.ts. The remaining Storage tests passed (772 passed, 12 skipped).

Breaking change

• Replace product imports such as @maka/core/permission and @maka/runtime/model-runtime with @maka/core and @maka/runtime.
• Node console diagnostic capture is now explicitly imported from @maka/core/node.
• Replace commands such as npm run e2e:computer-use-real with npm run e2e:computer-use -- real.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[Astro-Han]

Thanks for doing the hard consolidation work across the public API and Computer Use entry points. I reviewed the current head with four independent review slices plus a read-only ollama-cloud/deepseek-v4-flash:high pass.

The direction is sound: one public package surface and one data-driven Computer Use dispatcher remove parallel paths. The concrete issue is narrower: moving the Runtime prefix digest to the browser-safe helper also changed its memory model from incremental hashing to retaining every encoded row, concatenating them, and then allocating the SHA-256 padded copy. That is avoidable complexity in a hot persistence boundary.

The first-principles seam is a single incremental SHA-256 authority that accepts chunks in both browser-safe and Node contexts. Keep the canonical byte order exactly as it is, but feed the domain tag, identity, sequence, and event payload directly into the digest instead of constructing a whole-prefix buffer. That preserves the consolidation goal without making memory proportional to the serialized history.

I found no P0/P1. The P2 below should be handled, but it does not change the overall PASS gate. The no-subcommand behavior, mapping coverage, stale documentation references, and manifest-only export test are P3 cleanup opportunities rather than production blockers.

No local test suite was run during this review; conclusions are based on source and test inspection. Codex coordinated the independent passes and performed the final adjudication; external-model output was treated as unverified until checked against the code.

中文摘要

感谢这次对公共 API 和 Computer Use 入口的大规模收敛。方向是正确的：单一公共包入口和数据驱动 dispatcher 都在删除并行路径。

当前唯一需要处理的具体问题是 Runtime prefix digest 的内存模型从增量 hash 退化成了保存全部编码行、拼接整段 buffer，再由 SHA-256 创建 padding 副本。更符合第一性原理的方案是提供一个浏览器与 Node 都能使用的增量 SHA-256 权威，保持现有 canonical byte order，但逐块写入 domain tag、identity、sequence 和 event payload，不再构造整段历史 buffer。

未发现 P0/P1。下面的 P2 应处理，但整体 gate 仍为 PASS。其余无子命令行为、mapping 覆盖、文档引用和 manifest-only 测试都属于 P3 清理项，不应阻塞。

本次未在本地运行测试套件；结论来自源码和测试检查。Codex 协调了独立审查并完成最终判断，外部模型输出在核对代码前均视为未验证输入。

[Astro-Han]

P2 — Preserve incremental hashing for large Runtime prefixes. This now retains every encoded row in chunks, allocates the concatenated full-prefix buffer, and sha256Hex then allocates its padded working copy. The previous createHash().update(...) path kept extra memory bounded, so long sessions can now see a large avoidable peak on this persistence boundary. Please expose a browser-safe incremental SHA-256/chunked digest seam and feed the existing canonical pieces into it directly; add a focused large-prefix regression check that demonstrates memory does not scale with an additional whole serialized copy.

[Astro-Han]

/agentic_review

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

1. Stale Computer Use command 🐞 Bug ≡ Correctness

Description

Fix-now: the consolidation leaves docs/archive/computer-use-process-restart-e2e.md instructing
users to invoke the deleted npm run e2e:computer-use-process-restart script, causing npm’s
“Missing script” error instead of running restart recovery. The canonical equivalent is now `npm run
e2e:computer-use -- process-restart`.

Code

package.json[64]

+    "e2e:computer-use": "node scripts/computer-use.mjs"

Relevance

●●● Strong

Recent accepted documentation correctness precedent supports updating archived runbooks after
command-surface changes.

PR-#3197

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The package manifest removes the exact script still named by the archived runbook and exposes only
the consolidated Computer Use npm script. The canonical dispatcher maps process-restart to the
former launcher’s restart-recovery environment, proving that `npm run e2e:computer-use --
process-restart` is the direct replacement.

package.json[61-65]
docs/archive/computer-use-process-restart-e2e.md[129-133]
scripts/computer-use.mjs[6-10]
scripts/computer-use.mjs[8-10]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Computer Use script consolidation removes `e2e:computer-use-process-restart`, but the archived restart-E2E runbook still invokes it. Replace that invocation with the canonical dispatcher command; no new behavior, public command, or compatibility alias is needed.

## Issue Context
Use `npm run e2e:computer-use -- process-restart`. The deleted script set `MAKA_CU_AX_MODEL_SCENARIO=restart-recovery`, and the new dispatcher preserves that behavior under the `process-restart` command, so updating the existing documentation is the smallest correction.

## Fix Focus Areas
- docs/archive/computer-use-process-restart-e2e.md[129-133]
- package.json[64-65]
- scripts/computer-use.mjs[8-10]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Prefix hashing buffers entire history 🐞 Bug ➹ Performance

Description

Disposition: follow-up (non-blocking). digestCanonicalRuntimePrefix now retains byte chunks for
every encoded event, concatenates them into a second full-prefix buffer, and sha256Hex then
allocates a padded third buffer; the replaced Node hash streamed each chunk, so large runtime
prefixes have substantially higher peak allocation and can fail where they previously completed.

Code

packages/core/src/runtime-boundary.ts[R342-345]

+    chunks.push(uint64be(row.eventSeq));
+    chunks.push(lengthPrefixed(utf8(encodeCanonicalRuntimeEvent(row.event).json)));
  }
-  return `sha256:${hash.digest('hex')}`;
+  return `sha256:${sha256Hex(concatBytes(...chunks))}`;

Relevance

●● Moderate

Memory-allocation concern is plausible, but searches found no close accepted or rejected precedent
for this hashing pattern.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The changed path accumulates all event bytes, copies them into a single buffer, and passes that full
buffer to a one-shot implementation that creates another padded buffer. The public prefix-digest
entry point accepts an arbitrary row list and routes it through this code.

packages/core/src/runtime-boundary.ts[87-92]
packages/core/src/runtime-boundary.ts[337-345]
packages/core/src/runtime-boundary.ts[410-417]
packages/core/src/local-memory.ts[1058-1067]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Runtime-prefix digests now materialize the complete canonical byte stream before hashing. Restore bounded additional-memory processing by feeding the protocol prefix, identity, each event sequence number, and each event encoding incrementally to a platform-neutral SHA-256 implementation.

## Issue Context
The old Node `Hash` API supplied incremental updates but cannot remain in the browser-safe core root. No existing platform-neutral incremental hashing seam is available: `sha256Hex` is a one-shot API and necessarily pads a complete input buffer. Adding incremental state is therefore necessary; keep that state private to core (or expose only an internal helper) so it does not enlarge the public API or introduce a second digest authority.

## Fix Focus Areas
- packages/core/src/runtime-boundary.ts[337-345]
- packages/core/src/runtime-boundary.ts[410-417]
- packages/core/src/local-memory.ts[1058-1067]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

Review mode: 🧠 Deep: This is a broad public-contract refactor with multiple independent behavioral changes—package export boundaries, browser-safe core implementations, and a new Computer Use dispatcher—plus many consumers across runtime, storage, CLI, and desktop, making subtle defects plausibly easy to miss in one.

_{ⓘ  1 issues published inline · 2 in summary}

Tip of the day

💡 Did you know, you can keep summaries lean with Finding overflow, which tucks the rest behind 'View more'

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

1. Stale computer use command 🐞 Bug ≡ Correctness

Fix-now: the consolidation leaves docs/archive/computer-use-process-restart-e2e.md instructing
users to invoke the deleted npm run e2e:computer-use-process-restart script, causing npm’s
“Missing script” error instead of running restart recovery. The canonical equivalent is now `npm run
e2e:computer-use -- process-restart`.

Agent Prompt

## Issue description
The Computer Use script consolidation removes `e2e:computer-use-process-restart`, but the archived restart-E2E runbook still invokes it. Replace that invocation with the canonical dispatcher command; no new behavior, public command, or compatibility alias is needed.

## Issue Context
Use `npm run e2e:computer-use -- process-restart`. The deleted script set `MAKA_CU_AX_MODEL_SCENARIO=restart-recovery`, and the new dispatcher preserves that behavior under the `process-restart` command, so updating the existing documentation is the smallest correction.

## Fix Focus Areas
- docs/archive/computer-use-process-restart-e2e.md[129-133]
- package.json[64-65]
- scripts/computer-use.mjs[8-10]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[Astro-Han]

Approving at this head, converting my earlier verdict into an explicit approval. My previous review already concluded no P0/P1 and an overall gate of PASS: the one P2 is worth addressing but does not block, and the remaining items — no-subcommand behaviour, mapping coverage, documentation references, and the manifest-only test — are P3 cleanups. Nothing has changed on this head since; I was withholding the state, not the judgement.