feat(windows): feasibility spike for a supervised C#/.NET maka-cu Windows helper

[sunheyi6]

Relationship

Child of #3785 (Windows Computer Use epic), Phase 5 of the Windows roadmap in #2142. The bounded scope follows the maintainer clarifications in #3785, rather than its original broad implementation checklist.

Context

The maintainer preference for the bounded v1 preview is a C#/.NET helper supervised directly by the existing TypeScript host, subject to a small feasibility spike confirming packaging and lifecycle behavior on Windows. This issue is that spike: it does not define the final public protocol, deliver the production semantic v1 slice, or change macOS maka.cu.

Run against the published artifact in the intended packaged-app layout, initially a self-contained single-file exe, not only dotnet run. Single-file publishing is a hypothesis to test, not a reason to reject an otherwise viable .NET helper automatically.

Spike scope — six checks

1. Long-lived startup/handshake. Start and retain the helper; complete a bounded line-delimited JSON-RPC 2.0 handshake over stdio, with private protocol id maka.cu.windows/0 or an agreed private id, version, capabilities, and limits. Baseline host deadlines: handshake 10s, request 20s, then cancellation grace 2s where applicable. Record any divergence and its reason.
2. One MTA UIA observation. Use a dedicated non-UI MTA worker (CoInitializeEx(MTA)) and one explicitly selected, already-running top-level HWND. Bound tree nodes, depth, text/response size, and elapsed work. Bind the observation to pid + processStartTime + hwnd + windowGeneration and a retained UIA root. A traversal time budget alone is not proof that a blocked provider call can be interrupted; check 6 supplies the recovery boundary.
3. One supported semantic action. Implement set_value through ValuePattern; a click through Invoke/Toggle/SelectionItem is optional only if trivial. Resolve an opaque token only within its originating snapshot, atomically spend the snapshot before mutation dispatch, revalidate the target before and after dispatch, and use readback for typed verified/refused/unknown outcomes. Unknown outcomes never trigger automatic mutation replay.
4. Target-window WGC capture. Use IGraphicsCaptureItemInterop::CreateForWindow(HWND) for the same target generation. Report capture and action paths independently. Confirm that occluding the target does not substitute the covering window's pixels; return capture_unavailable on capture failure, with no silent screen-rectangle fallback. Tree and frame must identify the same target, without claiming temporal atomicity for dynamic content.
5. Cancellation with execution settlement. Exercise cancellation before dispatch, after dispatch, and while a provider call is blocked. Keep stdio/control handling responsive independently of the UIA worker. A cancellation ACK alone is not completion: the original request must settle with its actual outcome where known, or unknown if dispatch may have occurred. Before-dispatch cancellation must prove no mutation occurred. Release the execution lane only after the old operation has ended or the old helper has been confirmed terminated; do not report cancellation while abandoned work continues in the background. If the request cannot settle within the 2s grace, the host terminates the helper as in check 6. Killing the helper does not undo an action already delivered to the target.
6. Recovery after a hung provider. Use a deterministic fixture that blocks an actual UIA provider call; sleeping only inside the helper is insufficient evidence. The supervisor terminates and recreates the helper, not the user's target application/provider process. Confirm old-helper exit before admitting new work, advance helper generation, invalidate all old snapshots/tokens, and complete a fresh observe/action/readback against a responsive fixture target after restart. The target process must remain alive; release its injected hang through the test fixture if needed, and record that step. Specify restart count, backoff, recovery deadline, and whether restart is eager or next-request-driven. A successful handshake alone does not prove recovery.

Target identity and invalidation

Define how windowGeneration is established and invalidated, how it relates to the retained UIA root, and how helper generation scopes snapshots. A field with that name is not evidence of detecting HWND reuse. PID/start-time checks do not distinguish replacement windows within the same process.

Use the fixture to verify window close/recreation, control replacement, and duplicate use of a spent token. Ambiguous or changed identity must fail closed, never rematch by name/index. A replacement or modal HWND requires new explicit selection. No old token may become usable after helper restart.

Parent death and Windows shutdown

Treat stdin EOF as a shutdown trigger, not as sufficient proof of orphan prevention. Verify normal protocol shutdown/EOF and abrupt host termination, including while UIA is blocked. The helper must exit within a declared deadline without waiting indefinitely for its MTA worker; record residual-process evidence.

Evaluate an independent parent-liveness mechanism or a correctly owned Windows kill-on-close Job Object if EOF handling alone cannot establish that guarantee. Record the chosen ownership and handle-lifetime behavior. Do not copy the macOS SIGTERM graceful-shutdown assumption: Node terminates Windows children forcefully for these signals. Use protocol shutdown/EOF for the graceful path and a bounded forced-termination path.

Evidence environment

Run checks 1–6 on the published artifact on an interactive Windows 11 x64 desktop, with a deterministic adversarial fixture and committed reproduction scripts. Do not assume an ordinary GitHub-hosted runner supplies the required interactive desktop; local or self-hosted evidence is sufficient for this spike.

Include a clean-machine run with no installed .NET runtime or development SDK, copying only the declared deliverables. Record Windows build, Node/.NET SDK/CsWinRT versions, publish settings, artifact hashes, exact commands, and per-check pass/fail/blocked results. Do not treat a run blocked by environment setup as a demonstrated technical failure or a pass.

Packaging assumptions — verify or explicitly revise

• Initial target: self-contained single-file win-x64, with trimming disabled. Pin the actual Windows target framework/SDK version and all required native dependencies.
• Evaluate .NET 10 LTS as the forward-looking baseline. .NET 8 remains an allowed short-term spike choice with a documented reason and upgrade plan; its support ends 2026-11-10. Self-contained runtime patching requires rebuilding and redistributing the helper.
• Measure executable and total distribution size, native-library extraction location/permissions/footprint if applicable, cold/warm startup, first-frame latency, and memory. Do not assume a single exe implies no extraction or external prerequisites.
• Helper is a directly supervised TypeScript-host child over stdio, subject to the parent-death tests above. No orphan helper guarantee may rest only on graceful shutdown.
• Spike artifacts remain unsigned (signature: none / unsigned in spike metadata), with distributionReady: false. Authenticode and production distribution readiness are deferred; macOS adhoc signing terminology does not apply here.
• No changes to apps/desktop/bundled-tools.json pins and no new public protocol revision.

Decision points — measured evidence and recommendation

#	Decision	Evidence to collect
D1	Managed UIAutomationClient vs direct COM (UIAutomationCore)	Cache requests, UIA3 availability, thread/object ownership, provider timeout behavior
D2	Bounded base64 on stdout vs negotiated temporary files	Frame latency/size, base64/envelope overhead and response limits, stdout backpressure/control responsiveness; file ownership and cleanup if files are used
D3	CsWinRT/WGC publishing and runtime baseline	Clean-machine WGC, single-file/native extraction behavior, cold/warm timings, .NET version/support plan; self-contained multi-file feasibility if single-file fails
D4	Windows supervision divergences from MakaCuService	Cancellation settlement, blocked-provider recovery, confirmed exit, generation invalidation, restart budget, graceful shutdown and host-death evidence
D5	In-tree experiments/maka-cu-windows/ vs maka-agent/maka-cu	Integration findings; final code home decided after the spike
D6	Go compatibility boundary and any justified retention	Concrete existing CLI/MCP or distribution/integration requirements; no Go-to-.NET forwarding layer by default

Deliverables and completion criteria

• A draft prototype PR under the agreed code home, with fixture/reproduction scripts for the six checks and lifecycle/identity cases above.
• A measured results table with sizes, timings, memory, lifecycle evidence, and reproducible failure evidence where applicable.
• A short D1–D6 decision record: decision, evidence, recommendation, and every verified or revised packaging assumption.
• A go/no-go recommendation. A reproducible negative feasibility result can complete this research issue; it must not be presented as a successful preview implementation. Environmental blockers or untested assumptions are not a completed feasibility result.
• Proceed to the production child issue only when all six checks and the stated identity/parent-death cases pass against the selected published layout on the declared interactive environment, including clean-machine evidence. Any revised packaging choice must be explicit in the decision record and follow-up proposal.
• If single-file publishing fails, first isolate the cause and evaluate self-contained multi-file .NET distribution. Consider a long-lived Go helper only if measured language/distribution/integration constraints justify it, not automatically because one packaging mode failed.
• No macOS executor, bundled pin, public protocol, or foreground/global-input fallback changes. The helper speaks only the private protocol needed for the spike.

Non-goals

• No keyboard, scroll, coordinates, PostMessage, SendInput, or user-facing window manipulation. Fixture-driven window replacement is test setup only.
• No new consent/approval UI: reuse the existing product approval flow.
• No locked/session-0/secure-desktop/elevation support beyond typed capture_unavailable/refusal.
• No multi-monitor, mixed-DPI, or broad toolkit parity guarantees.
• No CI lane or production signing/distribution integration; these remain follow-up work.

References

• feat(windows): harden and productionize the maka-cu Computer Use executor #3785 (epic), roadmap(windows): make Windows a supported platform #2142 (roadmap).
• Maintainer scope and safety clarification; language trade-offs; maintainer spike direction.
• Host code to compare, not copy blindly: packages/computer-use/src/maka-cu-service.ts, stdio-json-rpc.ts, maka-cu-backend.ts, select-backend.ts; apps/desktop/bundled-tools.json, scripts/computer-use/prepare.mjs.
• UIA threading, WGC window interop, single-file deployment, .NET support policy, Node child termination, Windows Job Objects.

---

中文说明

关系与背景

本 issue 是 #3785（Windows Computer Use epic）的子项，属于 #2142 的 Phase 5。范围以 #3785 后续维护者澄清为准，不沿用正文原有的宽泛实现清单。

维持 C#/.NET helper 由现有 TypeScript host 直接监管的方向，通过小型 spike 验证 Windows 打包与生命周期可行性。本项不定义最终公开协议、不交付生产语义 v1 切片、不修改 macOS maka.cu。

必须使用目标应用打包布局中的发布产物，初始尝试 self-contained 单文件 exe，不能仅运行 dotnet run。单文件是待验证假设，失败不自动否定 .NET helper。

六项检查

1. 长驻启动与握手。 stdio 上使用换行分隔 JSON-RPC 2.0，私有协议 id 为 maka.cu.windows/0 或约定值，声明版本、能力和限制。基准为握手 10 秒、请求 20 秒、适用时追加取消宽限 2 秒；偏离需说明理由。
2. 一次 MTA UIA 观察。 专用非 UI MTA worker（CoInitializeEx(MTA)），仅操作显式选择且已运行的顶层 HWND。限制节点数、深度、文本/响应大小与耗时，绑定 pid + processStartTime + hwnd + windowGeneration 及 retained UIA root。遍历计时不能证明阻塞中的 provider 调用可中断，第 6 项负责恢复边界。
3. 一个受支持的语义动作。 必做 ValuePattern 的 set_value；仅在简单可用时选做 Invoke/Toggle/SelectionItem 点击。opaque token 只能在原快照内解析；变更派发前原子消费快照，动作前后校验目标，通过 readback 返回 verified/refused/unknown。结果未知时禁止自动重放变更。
4. 目标窗口 WGC 截图。 使用 CreateForWindow(HWND)，与观察绑定同一目标代次；capture/action 路径独立上报。验证窗口被遮挡时不会返回遮挡窗口的像素；失败返回 capture_unavailable，不静默回退屏幕矩形。树与帧必须属于同一目标，不承诺动态内容的时间原子性。
5. 取消与执行结束。 覆盖派发前、派发后和 provider 阻塞期间的取消。stdio/控制处理必须独立于 UIA worker 保持响应。取消 ACK 不等于完成：原请求必须以已知真实结果结束，可能已派发但无法确认时返回 unknown；派发前取消须证明没有变更。只有旧操作结束或旧 helper 确认退出后才能释放执行 lane，不能后台工作仍在运行就宣布取消完成。无法在 2 秒宽限内结束则进入第 6 项。终止 helper 不会撤销已经交给目标应用的动作。
6. provider 卡死后的恢复。 用确定性 fixture 阻塞真实 UIA provider 调用，仅在 helper 中 sleep 不算证据。supervisor 终止并重建的是 helper，不是用户目标应用/provider 进程。确认旧 helper 退出后才接收新工作，增加 helper 代次，使旧 snapshot/token 全部失效；重启后在可响应 fixture 目标上完成新的 observe/action/readback。目标进程必须存活；必要时通过 fixture 解除注入的阻塞，并记录此步骤。明确重启次数、退避、恢复时限以及立即重启还是下次请求触发；仅握手成功不算恢复。

目标身份与失效

定义 windowGeneration 如何建立/失效、与 retained UIA root 的关系，以及 helper 代次如何约束快照。增加同名字段不能证明识别了 HWND 复用；PID/创建时间也不能区分同一进程内的替换窗口。

fixture 应验证窗口关闭重建、控件替换、重复使用已消费 token。身份变化或无法确认时必须拒绝，不按名称/索引重新匹配。替换窗口或 modal HWND 必须重新显式选择；helper 重启后旧 token 不得重新有效。

父进程死亡与 Windows 关闭

stdin EOF 是关闭触发条件，不能单独证明没有孤儿进程。测试正常协议 shutdown/EOF，以及强制终止 host，包含 UIA 阻塞期间。helper 必须在声明时限内退出，不能无限等待 MTA worker，并提供残留进程检查证据。

若仅靠 EOF 无法保证，评估独立父进程存活监测或正确归属的 Windows kill-on-close Job Object，记录所有权与句柄生命周期。不要照搬 macOS 的 SIGTERM 优雅退出假设：Node 在 Windows 下通过这些信号强制终止子进程。正常路径使用协议 shutdown/EOF，异常路径有界强制终止。

证据环境

六项检查必须针对发布产物在交互式 Windows 11 x64 桌面运行，并提交确定性对抗 fixture 和复现脚本。不要假定普通 GitHub 托管 runner 提供所需交互桌面；本地或 self-hosted 证据足够。

补充一次未安装 .NET 运行时或开发 SDK的干净机器运行，只复制声明的交付物。记录 Windows build、Node/.NET SDK/CsWinRT 版本、发布参数、产物哈希、完整命令及每项 pass/fail/blocked。环境未就绪不能算技术不可行，也不能算通过。

打包假设——验证或明确修订

• 初始为 self-contained 单文件 win-x64，禁用 trimming；固定真实 Windows TFM/SDK 版本及所需原生依赖。
• 评估 .NET 10 LTS 作为后续基线。.NET 8 可作为有理由、有升级计划的短期 spike 选择，但其支持于 2026-11-10结束。self-contained 运行时补丁需重新构建并分发 helper。
• 测量 exe 与整体分发体积、原生库解压位置/权限/磁盘占用（如适用）、冷/热启动、首帧延迟及内存。单 exe 不代表无需解压或外部前置依赖。
• TypeScript host 通过 stdio 直接监管 helper，必须满足父进程死亡测试，不能仅凭正常退出宣称无孤儿。
• Spike 不签名，元数据使用 signature: none / unsigned，distributionReady: false；Authenticode 与生产分发留给后续。不使用 macOS adhoc 签名术语。
• 不修改 apps/desktop/bundled-tools.json pin，不引入公开协议版本。

决策记录 D1–D6

#	决策	证据
D1	托管 UIAutomationClient 或直接 COM	Cache request、UIA3、线程/对象所有权、provider 超时行为
D2	stdout 有界 base64 或协商临时文件	帧延迟/大小、base64 与信封开销、响应上限、stdout 背压及控制响应；文件方案需记录所有权与清理
D3	CsWinRT/WGC 发布方式和运行时基线	干净机器 WGC、单文件/原生库解压、冷/热启动、.NET 支持计划；单文件失败时评估 self-contained 多文件
D4	与 MakaCuService 的 Windows 监管差异	取消结束、provider 卡死恢复、确认退出、代次失效、重启预算、正常关闭及 host 死亡
D5	experiments/maka-cu-windows/ 或 maka-agent/maka-cu	集成发现；最终位置在 spike 后决定
D6	Go 兼容边界及保留理由	真实 CLI/MCP 或分发/集成需求，默认不增加 Go → .NET 转发层

交付与完成条件

• 在约定代码位置提交原型 draft PR，以及六项检查和上述生命周期/身份测试的 fixture、复现脚本。
• 实测结果表包含大小、耗时、内存、生命周期证据；失败时提供可复现证据。
• D1–D6 简短决策记录，列明决策、证据、建议及每项打包假设的验证/修订。
• 给出 go/no-go 建议。可复现的不可行结论也可完成研究 issue，但不能被描述为预览功能已实现。环境阻塞或未验证假设不算完成研究。
• 进入生产子 issue 的前提是：六项检查及身份/父进程死亡场景，在声明的交互环境中对选定发布布局全部通过，包括干净机器证据。打包选择修订须写入决策记录及后续提案。
• 单文件失败先定位原因，再评估 .NET self-contained 多文件分发；只有实测语言/分发/集成约束成立时才考虑长驻 Go helper，不因某种打包模式失败自动换语言。
• 不修改 macOS executor、bundled pin 或公开协议，不加入前台/全局输入 fallback；只实现 spike 所需私有协议。

非目标

• 不做键盘、滚动、坐标、PostMessage、SendInput 或产品窗口操作；fixture 窗口替换仅为测试设置。
• 不新增审批 UI，复用现有产品审批流程。
• 锁屏/session-0/安全桌面/提权仅返回 typed capture_unavailable/拒绝，不提供支持。
• 不承诺多屏、混合 DPI 或广泛 toolkit 对等性。
• CI、生产签名与分发集成留给后续。

参考链接与代码位置见上方英文 References；范围和选型分别对应 #3785 中 M4n5ter、sunheyi6、liugddx 的讨论。

[sunheyi6]

Codex-assisted implementation update, posted on behalf of @sunheyi6.

The draft prototype is available at #4346 (Refs #4318 and #3785). It is a feasibility checkpoint, not Windows Computer Use enabled in Maka, and does not close this issue. The end goal remains a usable Windows semantic preview through the existing maka_computer tool in the desktop application.

Current evidence

The published self-contained helper passed 34 lifecycle checks and 3 protocol regressions on an interactive Windows 11 Insider x64 development machine. This covers UIA observation/action readback, real target-window WGC with occlusion, cancellation, hung-provider recovery without killing the target, stale snapshots, whole-window recreation, and abrupt parent exit. Reproduction commands, artifact hashes, limits, and D1–D6 recommendations are in the PR.

These are fixture-level results. Same-window control replacement, clean-machine execution, and complete packaging measurements are still missing. This is an incomplete feasibility gate, not evidence that .NET is technically unsuitable.

Proposed repository ownership and paired PRs (D5 update)

Based on the existing repository split, the proposed long-term home for the native Windows executor is maka-agent/maka-cu, while the product-side integration remains in apache/maka. This is a concrete proposal for maintainer confirmation, not an already-approved relocation decision.

Repository / PR destination	Responsibility
Feature branch in sunheyi6/maka-cu → maka-agent/maka-cu:maka/base	C#/.NET Windows helper, UIA/WGC implementation, private child-protocol handling, native lifecycle/identity fixtures, and helper build/publish scripts.
Feature branch in sunheyi6/maka-agent → apache/maka:main	TypeScript child supervision, the Windows CuDispatchBackend adapter, backend selection/capability reporting, existing approval/session integration, helper resolution/hash verification, and desktop packaging/E2E.

The executor upstream currently uses maka/base as its default branch and already contains the experimental Go/PowerShell implementation under apps/OpenComputerUseWindows. The exact C# directory and treatment of that existing CLI/MCP surface need to be decided in the executor PR; do not silently remove compatibility or add a Go-to-.NET forwarding layer without a concrete requirement.

PR #4346 remains the current in-tree feasibility evidence and review checkpoint. It does not establish apache/maka/experiments/ as the permanent home of the production helper. Once maintainers confirm D5, migrate the native implementation and its relevant tests/build scripts into the executor repository, cross-link the two implementation PRs to each other and to #4318 / #3785, and retain a clear reference to the original experimental evidence rather than maintain two active helper implementations. This update does not move or close #4346.

The host integration PR must identify the corresponding executor commit/artifact and validate its protocol/capabilities and digest. Product activation and bundled pins remain subject to the feasibility and distribution gates below; code relocation alone does not satisfy them.

Proposed implementation sequence

1. Complete feat(windows): feasibility spike for a supervised C#/.NET maka-cu Windows helper #4318 before enabling the product preview.

   • Add deterministic same-window control replacement coverage and finish the HWND reuse / retained-root identity analysis; ambiguous identity must refuse without rematching by name or index.
   • Copy only the declared deliverables to an unlocked interactive Windows machine with no .NET runtime/SDK and run the complete suite; record the OS build and distinguish supported-release evidence from the existing Insider result.
   • Record cold/warm handshake, first-frame latency, memory, total distribution size, and native extraction location/permissions/footprint. Evaluate .NET 10 as the forward baseline; keep the current .NET 8 choice explicitly temporary.
   • Complete the packaging/parent-ownership decision record and evidence-based go/no-go recommendation. If single-file deployment fails, investigate self-contained multi-file before changing language. Signing stays deferred production distribution work, not an extra unsigned-spike gate.

2. After the feasibility gate passes, implement a bounded product child of feat(windows): harden and productionize the maka-cu Computer Use executor #3785.

   • Confirm the D5 repository split above with maintainers, implement the native helper in maka-agent/maka-cu and the host adapter/supervisor in apache/maka, and remove or restrict fixture/debug endpoints from product builds.
   • Add a Windows adapter at the platform-neutral CuDispatchBackend boundary. Keep the child protocol private; do not make Windows impersonate the literal macOS maka.cu/2 wire.
   • Move lifecycle supervision from reproduction drivers into the real TypeScript host: bounded handshake/request deadlines, cancellation settlement, confirmed old-helper exit before replacement, generation invalidation, and a capped restart/backoff policy. Establish parent ownership with an appropriate Windows mechanism and test it.
   • Support explicit selection of one already-running top-level HWND, bounded UIA observation and WGC, set_value through ValuePattern, and click_element only for advertised Invoke/Toggle/SelectionItem patterns. Spend snapshots before mutation and return verified/refused/unknown after revalidation/readback; never automatically replay an unknown mutation.

3. Connect the existing product policy and packaging path.

   • Wire the Windows backend into selection/capability reporting and the desktop's binary resolver, hash verification, preparation and packaging flow without changing the macOS path or bypassing artifact-readiness checks.
   • Reuse the existing approval/session policy; refuse password fields, locked/secure desktops, inaccessible/elevated targets, ambiguous targets and unsupported actions with appropriate typed results. A replacement or modal HWND requires new explicit selection.
   • Report capture and action capabilities independently. Capture failure must remain capture_unavailable; no screen-rectangle or foreground/global-input fallback.
   • Address signing and bundled-runtime servicing as part of distributable preview readiness, rather than describing an unsigned development artifact as release-ready.

4. Accept the feature through the actual packaged Maka flow.

   • On the supported Windows environment, install/start Maka and exercise explicit target selection → existing approval → maka_computer observation → opaque-token action → fresh readback, using the adversarial fixture and at least one supported real application.
   • Verify cancellation, target close/replacement, blocked-provider recovery, app shutdown and abrupt host exit; no helper leftovers and no target-process termination by the supervisor.
   • Run host/runtime regression tests, verify macOS behavior remains unchanged, and document supported controls plus refusal/recovery behavior.

User-visible completion criterion: a user can operate a supported, explicitly selected Windows application from a Maka conversation without manually starting a helper or running a test driver. Passing fixture scripts alone does not meet this criterion.

Keyboard/coordinate input, scrolling, window manipulation, arbitrary app launch, mixed-DPI/multi-monitor guarantees, and broad toolkit parity remain separate follow-ups under #3785. The first preview must not advertise them as supported.

The draft PR can collect review while the remaining feasibility evidence is gathered. Product integration can be planned in parallel, but neither a draft submission nor its merge waives the #4318 gate. Feedback is requested on this sequence and the eventual maintained code home; no new child issue is being marked complete or created implicitly by this comment.

中文说明

此更新由 Codex 协助、代表 @sunheyi6 发布。实验 Draft PR：https://github.com/apache/maka/pull/4346，关联 #4318 和 #3785，不关闭当前 issue，也不代表 Maka 已支持 Windows Computer Use。最终目标是用户安装并启动 Windows 版 Maka 后，直接在对话中操作支持的指定应用，无需手动运行 helper 或测试脚本。

本机交互式 Windows 11 Insider 上，发布产物通过 34 项生命周期和 3 项协议检查，覆盖 UIA 操作回读、真实 WGC 遮挡截图、取消、卡死恢复、旧快照、窗口重建和父进程退出。仍缺同窗口控件替换、无 .NET/SDK 的干净机器运行及完整打包测量；这是证据未齐，并非证明 .NET 不可行。

双仓库归属与配套 PR（D5 更新）

依据现有架构，建议正式原生执行器放在 maka-agent/maka-cu，产品接入留在 apache/maka。这是待维护者确认的具体方案，并非已经批准迁移。

PR 目标	职责
sunheyi6/maka-cu 的功能分支 → maka-agent/maka-cu:maka/base	C#/.NET helper、UIA/WGC、私有子进程协议、原生生命周期/身份测试及 helper 构建发布脚本。
sunheyi6/maka-agent 的功能分支 → apache/maka:main	TypeScript 监管、Windows 后端适配和选择、能力报告、现有授权/会话接入、二进制定位与哈希校验、桌面打包和端到端验证。

执行器上游默认分支目前是 maka/base，已有 apps/OpenComputerUseWindows Go/PowerShell 实验实现。C# 的具体目录以及原 CLI/MCP 兼容面的处理应在执行器 PR 中明确；不能直接删除兼容面，也不默认增加只有转发职责的 Go → .NET 中间层。

现有 #4346 保留为主仓库内的实验验证和审阅入口，不据此决定正式 helper 长期放在主仓库。维护者确认 D5 后，将原生实现及相应测试/构建脚本迁入 maka-cu，两边功能 PR 互相链接，并关联 #4318 和 #3785；保留原实验记录的引用，避免长期维护两份活动实现。本次更新不迁移或关闭 #4346。

主仓库接入 PR 需明确对应的执行器 commit/产物，校验协议、能力和摘要。功能启用和 bundled pins 仍需满足下述实验验收及正式分发要求，迁移代码本身不等于验收通过。

后续建议分四步：

1. 补齐 feat(windows): feasibility spike for a supervised C#/.NET maka-cu Windows helper #4318 验收：确定性控件替换和 HWND 复用分析；干净交互式 Windows 验证；记录稳定系统版本、冷/热启动、首帧、内存、包体和原生库解压权限/占用；评估 .NET 10；完成打包和父进程所有权决策。单文件若有问题，先验证自包含多文件方案。签名属于正式分发工作，不追加成实验门槛。
2. 验收通过后实施 feat(windows): harden and productionize the maka-cu Computer Use executor #3785 的受限功能子项：由维护者确认上述双仓库归属，原生 helper 在 maka-cu 实施，host 适配/监管在 apache/maka 实施；产品构建移除或限制调试接口；接入平台中立后端，不冒充 macOS 私有实现；把测试驱动中的生命周期监管迁入正式 TypeScript host；支持显式选择一个已运行 HWND、UIA/WGC、ValuePattern 填值及明确声明支持的语义点击。快照先消费、动作前后校验，未知结果禁止自动重放。
3. 接入现有产品策略和打包：Windows 后端选择、能力报告、二进制定位和哈希校验；复用现有授权流程，不绕过发布就绪检查；密码、锁屏、安全桌面、权限不足和不支持的操作明确拒绝；替换窗口/modal 重新显式选择；截图失败不降级到屏幕矩形或全局输入。正式分发再处理签名和运行时维护。
4. 以真实 Maka 安装包验收：在支持的 Windows 环境中，从对话走完选择目标 → 授权 → 观察 → token 操作 → 新观察回读；既测对抗 fixture，也测至少一个支持的真实应用，覆盖取消、窗口替换、卡死恢复和退出清理，并验证 macOS 不回归。

键盘、坐标、滚动、窗口操纵、任意应用启动、多屏/混合 DPI 和广泛 toolkit 兼容性仍归后续扩展，首版不能宣称支持。Draft PR 可在补证据期间收集审阅，但提交或合并都不能替代 #4318 的验收。欢迎维护者确认实施顺序及最终代码归属；本评论不隐式创建或关闭新的子 issue。

[sunheyi6]

Codex-assisted implementation update, posted on behalf of @sunheyi6.

@liugddx @M4n5ter — the repository split proposed above is now implemented as two linked Draft PRs:

• Native Windows executor: maka-agent/maka-cu#5
• Maka host/product integration: apache/maka#4409
• Original in-tree feasibility checkpoint: apache/maka#4346

What is now implemented

The native helper lives in maka-agent/maka-cu without replacing the existing Go CLI/MCP surface. It provides the private maka.cu.windows/0 protocol, explicit-HWND UIA observation, one-use opaque tokens, verified set_value and click_element, target-window WGC capture, target/generation revalidation, cancellation, bounded output, parent-death handling, and helper recovery.

The Maka PR adds a dedicated TypeScript supervisor and CuDispatchBackend, selects windows-native on Windows, verifies the helper digest, invalidates every session after helper-generation loss, preserves outcome_unknown for delivered mutations, and adds Desktop manifest/packaging gates. It does not add global coordinate, keyboard, foreground-input, screen-rectangle, or silent retry fallbacks.

New evidence

• native protocol regressions: 4/4
• native interactive lifecycle suite: all checks passed
• same-window control replacement: covered and passed
• whole-window recreation and stale-token rejection: passed
• WGC target capture under occlusion: passed
• blocked-provider recovery, cancellation settlement, abrupt parent exit, and residual-process checks: passed
• real Maka host adapter → published .NET helper → WinForms fixture integration: 2/2
  • initialize/preflight/window enumeration
  • observe with WGC screenshot → set_value → fresh observe and readback verification
• focused Host/backend/supervisor tests, builds, formatting, and ASF header checks passed

This proves the source-development path across both repositories. It still does not meet the user-visible completion criterion of a released Windows Maka build that operates a real application from a conversation without preparation.

Updated next steps

1. Review and land the native helper ownership/API in feat(windows): add native Computer Use helper maka-agent/maka-cu#5.
2. In feat(computer-use): integrate Windows native backend #4409, pin an accepted executor commit/artifact and keep distributionReady: false until provenance, servicing, and release ownership are approved.
3. Complete the clean-machine run with no installed .NET runtime/SDK and record the requested startup, first-frame, memory, size, and extraction measurements; evaluate the .NET 10 baseline.
4. Run the packaged Desktop acceptance path through existing target approval and maka_computer against both the adversarial fixture and at least one supported real application.
5. Verify packaged cancellation/restart/shutdown behavior and macOS regression coverage, then enable the Windows manifest entry only for the qualified artifact.

Could you review the two-PR boundary and the remaining release gate, especially whether the native PR should target maka/base as submitted and whether the host PR's private supervisor/adapter is the intended product integration seam?

中文说明

此更新由 Codex 协助、代表 @sunheyi6 发布。

此前建议的双仓库方案已经落成两个互相关联的 Draft PR：

• Windows 原生执行器：maka-agent/maka-cu#5
• Maka Host/产品接入：apache/maka#4409
• 原主仓库实验检查点：apache/maka#4346

原生 helper 已实现私有协议、显式 HWND 的 UIA 观察、一次性 token、可验证的填值/点击、指定窗口 WGC 截图、身份校验、取消、父进程退出和卡死恢复。Maka 侧已实现独立监管器、Windows backend、摘要校验、全会话失效、outcome_unknown 保留以及 Desktop 清单/打包门禁，没有加入全局输入或屏幕矩形降级。

真实跨仓库联调已通过：Maka Host 启动发布版 .NET helper，观察 WinForms fixture 并取得 WGC 截图，执行 set_value，随后重新观察确认值已更新；同窗口控件替换、窗口重建、遮挡截图、取消、卡死恢复和父进程退出也都已有通过证据。

这已经证明源码开发路径可用，但还不等于用户安装正式 Windows Maka 后能直接在对话里操作真实应用。剩余工作是：维护者确认并合并 helper 归属/API；固定接受的 commit/产物；完成无 .NET/SDK 干净机器和性能/体积测量；通过现有授权与 maka_computer 跑完整打包应用验收；最后才把合格产物标记为可分发。

请重点审阅两个 PR 的职责边界、maka/base 目标分支是否正确，以及 Host 私有监管器/适配层是否符合预期。

[M4n5ter]

English

Here, CUA refers to the open-source trycua/cua project, specifically its Rust-based Cua Driver Windows backend, rather than a generic acronym.

I think the current direction has a fundamental problem: #4318 is presented as a feasibility study, but it is already being used to justify a preselected production architecture. The order is backwards.

1. This is solution-first rather than problem-first

The issue starts from “a supervised C#/.NET helper” and then asks whether that choice can be made to work. It does not compare the realistic alternatives before the linked PRs commit Maka to:

• a new language/runtime;
• a new private protocol;
• a dedicated Windows supervisor;
• a separate executor repository;
• a new packaging and servicing path.

A successful spike would prove only that .NET is feasible. It would not prove that this is the simplest or best production architecture.

This is no longer theoretical. CUA implements UIA and WGC directly in Rust and provides a reusable private-worker model over inherited stdio. Its released Windows x64 main executable is approximately 28.7 MB, compared with the currently reported approximately 180 MB .NET executable plus companion DLLs. These numbers are not directly comparable, but they are more than sufficient to require Rust/direct-COM as a real option in the architecture decision.

The current decision table excludes that option. That is a selection bias, not a completed architecture evaluation.

2. The proposed result is not sufficiently useful as Windows Computer Use

The issue defines an excellent set of safety and recovery invariants, but its supported product surface is essentially:

• observe one selected HWND;
• capture it with WGC;
• perform set_value;
• optionally invoke a small subset of UIA patterns.

That is a useful experiment, but it is not a credible Windows Computer Use preview. Many real Windows applications expose incomplete, misleading, or blocked UIA trees. A backend that safely refuses most practical tasks is still not a usable backend.

CUA demonstrates the actual compatibility problem: real coverage requires routing across UIA, MSAA, modern capture, toolkit-specific behavior, background delivery, and explicitly authorized escalation. Maka should keep stricter guarantees than CUA—no silent screen capture fallback, no automatic replay of unknown mutations, and no unapproved foreground/global input—but strictness cannot be used as a substitute for usability.

Before approving a production architecture, we need a real application/task matrix and a comparative baseline. It should cover at least classic Win32, WPF, WinUI3/UWP, Electron/Chromium, and one problematic legacy provider, exercising observation, text entry, invoke/select/toggle, scrolling, dynamic replacement, cancellation, recovery, and a complete task through the packaged Maka conversation flow.

If the proposed architecture cannot approach CUA-level task coverage without accumulating additional supervisors, protocol extensions, special cases, and fallback layers, then it is the wrong architecture and should be rejected before merge.

3. WindowsCuService duplicates lifecycle authority

#4409 introduces a substantial Windows-specific supervisor alongside the existing MakaCuService. Both own process spawning, handshake, pending requests, cancellation, timeouts, restart, generation invalidation, and disposal.

That duplication is not a Windows requirement. It is an architectural defect.

The shared boundary should be:

Maka Runtime
  -> one shared supervised-child RPC/lifecycle core
  -> thin platform backend
  -> isolated native executor

Windows-specific code should describe Windows capabilities and behavior. It should not reimplement generic child-process lifecycle authority.

4. The feasibility gate is still incomplete

The linked implementation still lacks the evidence explicitly required by this issue:

• clean-machine execution without an installed .NET runtime or SDK;
• complete distribution size, startup, first-frame, and memory measurements;
• .NET 10 evaluation and runtime-servicing decision;
• accepted artifact provenance and release ownership;
• packaged Desktop acceptance through the real approval and conversation flow.

Despite this, the work has already expanded into three PRs, two repositories, a product backend, a dedicated supervisor, and packaging machinery.

That is scope inversion: the product skeleton has been built before the research question has been closed.

Required correction

I do not think the current linked implementation should be treated as an approved production direction, even if its focused tests pass.

Before proceeding:

1. Keep feat(windows): feasibility spike for a supervised C#/.NET maka-cu Windows helper #4318 strictly as a disposable go/no-go experiment for the .NET hypothesis.
2. Do not infer production-language, repository-boundary, or supervisor approval from its success.
3. Add an explicit architecture decision comparing the measured .NET result with a minimal Rust/direct-Windows implementation. CUA is evidence that this alternative is technically real, not necessarily a dependency to adopt wholesale.
4. Replace the parallel supervisor design with one shared supervised-child lifecycle core.
5. Define and pass a real-application usability gate, using CUA on the same machine and task matrix as a comparative baseline.
6. Keep distributionReady: false and do not enable the product path until clean-machine, provenance, servicing, packaged E2E, and usability evidence are complete.

The current work may be valuable feasibility evidence. It is not yet evidence that Maka has selected an elegant, maintainable, or sufficiently useful Windows architecture.

中文

这里的 CUA 指开源项目 trycua/cua，具体是其基于 Rust 的 Cua Driver Windows backend，不是泛指 Computer Use Automation。

我认为当前方向存在一个根本问题：#4318 名义上是可行性研究，实际上已经被用来论证一个预先选定的生产架构。顺序反了。

1. 当前流程是先选方案，再证明方案

Issue 从“受监管的 C#/.NET helper”出发，然后验证怎样让它工作。在相关 PR 已经让 Maka 承担以下长期成本之前，并没有先比较现实可行的替代方案：

• 新语言和运行时；
• 新私有协议；
• Windows 专用 supervisor；
• 独立 executor 仓库；
• 新的打包和运行时维护路径。

Spike 成功只能证明 .NET 可行，不能证明它是最简单或最优的生产架构。

这已经不是理论问题。CUA 使用 Rust 直接实现了 UIA 和 WGC，并提供了基于继承 stdio 的通用 private-worker 模型。它发布的 Windows x64 主程序约 28.7 MB，而当前 .NET helper 据报约 180 MB，另带多个 DLL。两者功能范围不同，不能直接作为性能结论，但已经完全足够要求在架构决策中正式评估 Rust/direct-COM 路线。

当前决策表没有这个选项。这是选型偏置，不是完整的架构评估。

2. 当前结果不足以构成可用的 Windows Computer Use

Issue 对安全和恢复约束定义得很好，但实际支持面基本只有：

• 观察一个显式选择的 HWND；
• 通过 WGC 截图；
• 执行 set_value；
• 可选支持少数 UIA pattern。

这可以作为实验，但不能算可信的 Windows Computer Use preview。很多真实 Windows 应用的 UIA tree 不完整、不准确，甚至会阻塞。一个能够安全拒绝大部分实际任务的 backend，仍然不是可用的 backend。

CUA 展示了真正的兼容性问题：真实应用覆盖需要 UIA、MSAA、现代截图、toolkit 特殊行为、background delivery 和经过明确授权的升级路径。Maka 应保持比 CUA 更严格的约束——不静默降级到屏幕截图、不自动重放未知 mutation、不在未经授权时使用前台或全局输入——但不能用严格性代替可用性。

在批准生产架构之前，需要真实应用和任务矩阵，并加入对照基线。至少应覆盖经典 Win32、WPF、WinUI3/UWP、Electron/Chromium 和一个存在兼容性问题的旧式 provider，测试观察、文本输入、invoke/select/toggle、滚动、动态替换、取消、恢复，以及通过打包 Maka 对话流程完成的完整任务。

如果当前架构必须不断增加 supervisor、协议扩展、特殊分支和 fallback，才能接近 CUA 的任务覆盖率，那么它就是错误架构，应在合并前否决，而不是继续打补丁。

3. WindowsCuService 重复了生命周期 authority

#4409 在现有 MakaCuService 旁边增加了较大的 Windows 专用 supervisor。两者都负责进程启动、握手、pending request、取消、超时、重启、generation 失效和销毁。

这种重复不是 Windows 平台要求，而是架构缺陷。

正确边界应该是：

Maka Runtime
  -> 一套共享的 supervised-child RPC/生命周期核心
  -> 很薄的平台 backend
  -> 隔离的原生 executor

Windows 代码应该描述 Windows 能力和行为，而不是重新实现通用子进程生命周期 authority。

4. 可行性门槛仍未完成

当前实现仍缺少本 issue 明确要求的证据：

• 未安装 .NET runtime/SDK 的干净机器运行；
• 完整包体、启动、首帧和内存测量；
• .NET 10 评估及运行时维护决策；
• 被接受的产物来源和发布责任；
• 通过真实授权及对话流程的打包 Desktop 验收。

但整个工作已经扩展为三个 PR、两个仓库、一个产品 backend、一套专用 supervisor 和打包机制。

这是范围倒置：研究问题尚未关闭，产品骨架已经先建好了。

必须调整的地方

即使当前局部测试全部通过，我也不认为相关实现已经可以被视为得到批准的生产方向。

继续推进前应当：

1. 严格把 feat(windows): feasibility spike for a supervised C#/.NET maka-cu Windows helper #4318 保持为验证 .NET 假设的可抛弃 go/no-go 实验。
2. 不从实验成功推导出正式语言、仓库边界或 supervisor 设计已经获批。
3. 增加明确的架构决策，对比实测 .NET 结果与最小 Rust/direct-Windows 实现。CUA 证明这个替代方案真实存在，但不代表必须整体依赖 CUA。
4. 用一套共享的 supervised-child 生命周期核心替代并行 supervisor。
5. 定义并通过真实应用可用性门槛，在同一机器和任务矩阵上以 CUA 作为对照基线。
6. 在干净机器、产物来源、运行时维护、打包 E2E 和可用性证据完成前，保持 distributionReady: false，不启用产品路径。

当前工作可以成为有价值的可行性证据，但它还不能证明 Maka 已经选中了优雅、可维护且具有足够实际价值的 Windows 架构。

[sunheyi6]

Thanks for the detailed architecture review. I understand the concern that the current .NET implementation should remain feasibility evidence rather than be treated as an approved production architecture.

I will next implement a minimal Rust/direct-COM Windows backend as a comparative prototype and run it against the same application/task matrix and lifecycle checks as the C#/.NET helper. The comparison will cover UIA observation and semantic actions, target-window WGC capture, cancellation and hung-provider recovery, packaging and clean-machine behavior, startup/first-frame latency, memory, distribution size, and practical task coverage.

I will keep the current .NET work clearly scoped as a feasibility experiment, preserve distributionReady: false, and avoid treating the existing supervisor or repository boundary as final. After the comparative evidence is available, we can make an explicit architecture decision and then decide which implementation should move into the production path.

中文说明

感谢这次详细的架构审查。我已经理解当前 .NET 实现应保持为可行性证据，不能直接视为已经批准的生产架构。

接下来我会实现一个最小的 Rust/direct-COM Windows 对照原型，并使用与 C#/.NET helper 相同的应用/任务矩阵和生命周期检查进行测试。对比范围包括 UIA 观察和语义动作、目标窗口 WGC 截图、取消与 provider 卡死恢复、打包和干净机器运行、启动/首帧延迟、内存、分发体积以及实际任务覆盖率。

当前 .NET 工作会明确保持为可行性实验，继续保留 distributionReady: false，也不会把现有 supervisor 或仓库边界当成最终决定。完成对比证据后，再明确决定生产架构，并确定哪一种实现进入正式产品路径。

[hqhq1025]

Maintainer direction after reviewing the current proposals and the existing macOS execution boundary:

The production contract will be established by:

• refactor(computer-use): enforce semantic-only actions and enable guarded keyboard input #4497: one global, semantic-only model action space
• refactor(host): reject point dispatch at the protocol boundary maka-agent/maka-cu#6: dispatch.point retained only as a stable fail-closed compatibility endpoint

Windows should now build on those two foundations.

The required architecture is:

Maka Runtime
  -> one shared supervised-child RPC/lifecycle core
  -> one thin platform adapter
  -> a native executor implementing maka.cu/2

This means:

1. Windows and macOS expose the same model action schema. Do not keep Windows-specific schema narrowing or a second adapter surface.
2. maka-cu is the only native executor boundary. A Windows implementation should implement the shared maka.cu/2 semantic contract rather than introduce a production maka.cu.windows/0 contract.
3. Generic process lifecycle authority must be shared. Windows-specific code may provide platform capabilities, process details, UIA/WGC behavior, and packaging metadata, but should not duplicate spawn, handshake, pending-request, cancellation, timeout, restart, generation, and disposal ownership.
4. Coordinate mutation is outside the production action space. There must be no semantic-to-pixel fallback, foreground fallback, or path that feeds presentation geometry back into execution.
5. Internal native events are acceptable only as the implementation of an already observation-bound semantic action. They must remain PID/HWND-bound and must not accept model coordinates.

The C#/.NET and Rust/direct-COM work should continue as executor implementation evidence, not as competing product contracts. Compare them behind the same protocol and with the same matrix:

• UIA identity fidelity, stale/replaced control refusal, and one-use observation authority
• semantic coverage for invoke, value, selection/toggle, text selection, and element scrolling
• target-window WGC capture
• cancellation, hung-provider recovery, parent death, and no residual helper processes
• cold/warm startup, first observation, memory, complete distribution size, and clean-machine behavior
• real tasks across Win32, WPF, WinUI/UWP, Electron/Chromium, and a problematic legacy provider

For every submitted revision, please list the exact local machine/OS, applications, tasks, commands, passed checks, skipped checks, and known unsupported cases in the PR description. Keep distributionReady: false until artifact provenance, servicing ownership, clean-machine qualification, and packaged Maka conversation-level acceptance are complete.

For the next step, please rework the native proposal on top of maka-agent/maka-cu#6 and rework #4409 after #4497. The existing .NET work remains useful comparative evidence; it should not be merged as a second permanent protocol/supervisor stack.