Skip to content

feat(runtime-host): add Desktop client foundation - #2134

Merged
M4n5ter merged 2 commits into
mainfrom
feat/runtime-host-desktop-client-foundation
Aug 4, 2026
Merged

feat(runtime-host): add Desktop client foundation#2134
M4n5ter merged 2 commits into
mainfrom
feat/runtime-host-desktop-client-foundation

Conversation

@M4n5ter

@M4n5ter M4n5ter commented Aug 4, 2026

Copy link
Copy Markdown
Member
English

Summary

  • Add a compatibility epoch while keeping the Runtime Host wire protocol at v0, so a Client can reject and retire a stale same-version Host before using incompatible semantics.
  • Add bounded canonical transcript snapshots and absolute live-stream offsets, allowing late or reconnecting Clients to reconstruct a Session and continue following an active Turn without gaps or duplicate ownership.
  • Expose transcript loading through the Runtime Host Client API and add the first Desktop main-process lifecycle/session adapter seam.

Why

Desktop is the first M4 Client adapter. It needs a reliable initial-state/live boundary before its existing renderer-facing flows can move from the embedded Runtime to the Host. Wire version v0 alone cannot distinguish a pre-foundation Host from one that supports this boundary.

Design

  • session.transcript.query creates immutable, subscription-owned snapshots with bounded chunks, memory limits, idle expiry, and connection/session cleanup.
  • Active transcripts are projected from the canonical Session and Runtime Event stores. The reader preserves the Store's existing stream fold instead of creating a second transcript journal.
  • Live assistant deltas carry absolute UTF-16 offsets, including across periods with no subscribers, so Clients can detect overlap or a gap.
  • The Desktop adapter owns only Host connection and subscription lifecycles. It does not open writer Stores or construct an embedded Runtime owner.
  • Desktop production bootstrap is intentionally unchanged. The Host-backed path will replace the embedded owner atomically in M5 rather than introducing dual ownership or fallback.

Validation

  • npm test --workspace @maka/runtime-host
  • npm test --workspace @maka/desktop (1,618 tests)
  • npm test --workspace maka-agent
  • npm run format:check
  • npm run lint
  • npm run typecheck
  • npm run build --workspace @maka/desktop
  • Existing embedded Desktop regression smoke covering renderer mount, new Session creation, streaming completion, SQLite persistence, the preload/IPC bridge, and error-surface absence.

Part of #2010.

简体中文

概要

  • 在 Runtime Host wire protocol 继续保持 v0 的同时加入 compatibility epoch,使 Client 能在使用不兼容语义前识别并淘汰同版本的陈旧 Host。
  • 加入有界 canonical transcript snapshot 与 live stream 绝对 offset,使中途加入或重连的 Client 能重建 Session,并在不产生缺口或重复 ownership 的情况下继续跟随正在执行的 Turn。
  • 通过 Runtime Host Client API 暴露 transcript 加载能力,并提供首个 Desktop main-process lifecycle/session adapter 接入边界。

原因

Desktop 是第一个 M4 Client adapter。在现有 renderer-facing flow 从 embedded Runtime 迁移到 Host 前,需要先具备可靠的 initial-state/live 边界。仅靠 wire version v0 无法区分不具备该边界的旧 Host 与当前 Host。

设计

  • session.transcript.query 创建由 subscription 持有的 immutable snapshot,并限制 chunk、内存占用和空闲时间,同时在 connection/session 结束时完成清理。
  • active transcript 从 canonical Session Store 与 Runtime Event Store 投影。reader 复用 Store 已有的 stream fold,不创建第二份 transcript journal。
  • live assistant delta 携带 UTF-16 绝对 offset;即使一段时间没有 subscriber,offset 也连续,使 Client 能识别 overlap 或 gap。
  • Desktop adapter 只拥有 Host connection 与 subscription lifecycle,不打开 writer Store,也不构造 embedded Runtime owner。
  • Desktop production bootstrap 有意保持不变。Host-backed path 将在 M5 原子替换 embedded owner,不在 M4 引入 dual ownership 或 fallback。

验证

  • npm test --workspace @maka/runtime-host
  • npm test --workspace @maka/desktop(1,618 tests)
  • npm test --workspace maka-agent
  • npm run format:check
  • npm run lint
  • npm run typecheck
  • npm run build --workspace @maka/desktop
  • 对现有 embedded Desktop 执行 regression smoke test,覆盖 renderer mount、新建 Session、streaming completion、SQLite persistence、preload/IPC bridge,并确认未出现 error surface。

#2010 的一部分。

@M4n5ter

M4n5ter commented Aug 4, 2026

Copy link
Copy Markdown
Member Author

CI note: the remaining E2E failure is in the existing embedded Desktop composer-skill-invocation flow, where the second staged Skill chip did not appear within its timeout. This PR does not change that flow. The affected Runtime Host, Desktop workspace, typecheck, and aggregate test lanes all pass.

@M4n5ter
M4n5ter marked this pull request as ready for review August 4, 2026 10:38
@M4n5ter
M4n5ter merged commit 8717e82 into main Aug 4, 2026
9 of 11 checks passed
@M4n5ter
M4n5ter deleted the feat/runtime-host-desktop-client-foundation branch August 4, 2026 10:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant