maka/docs/computer-use-provenance.md

<!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
-->

# Computer Use provenance

Maka's Computer Use surface was built against other people's work in three
materially different ways. They are separated here because the obligations
differ: redistribution under a license, adaptation or reference use of licensed
source, and inspection of a proprietary implementation for compatibility.

At a high level, Maka's Computer Use implementation was informed by the
MIT-licensed `trycua/cua` and `iFurySt/open-codex-computer-use` projects and by
comparison with Codex Desktop's implementation and externally visible
behavior. Maka integrated and adjusted those inputs through its own testing,
safety boundaries, and product requirements.

That summary does not collapse the source categories below. Licensed source,
behavior observations, exact facts recovered from a binary, and Maka-authored
work remain separate because their evidence and release-review obligations are
different.

Paths are Maka's unless they carry the upstream repository name, as in
`open-codex-computer-use/...`.

Every entry names what was taken, where it landed, and what the evidence was.
When you add or change a borrowed design, add the row here and put the same
statement in the file that carries it — an in-file comment answers "why is this
constant 200?" at the moment someone asks it, and this file answers "what did we
build on?" for the project as a whole.

## 1. Redistributed under license

Ships inside the Maka artifact. Requires the license text and copyright notice
to travel with it.

| Component | License | Where the notice lives |
|---|---|---|
| npm dependencies | various | `apps/desktop/resources/licenses/npm/`, generated by `scripts/generate-third-party-notices.mjs` and byte-checked at build by `scripts/check-third-party-notices.mjs` |

Maka has one Computer Use executor, `maka-cu`. It is built from Maka's own
source by the `prepare` command in `scripts/computer-use.mjs` and pinned by digest in
`apps/desktop/bundled-tools.json`. It is not signed, so it is not distributed:
its `distributionReady` is false and `scripts/verify-macos-arm64-dmg.mjs`
forbids its path in a packaged build. Nothing third-party ships inside the Maka
artifact for Computer Use, which is why the table above has one row.

The third-party executor Maka used to run, cua-driver, was removed along with
its vendored notice. Nothing in this tree spawns it or links against it.

`maka-cu` is itself a fork of MIT-licensed `iFurySt/open-codex-computer-use`
(§2), so when it does ship, that notice travels with it.

## 2. Licensed source adapted or read as reference

MIT-licensed source was used both as an implementation starting point and as a
design reference. The rows below distinguish adaptation from reference-only
use.

### trycua/cua

MIT. The original Maka cursor renderer was a TypeScript adaptation of the
public `cursor-overlay` crate, introduced in Maka commit
`025d0c628a2162d0a7daf49e97d104c36a4431c6`. The fixed upstream source recorded
by Maka's bundled cua-driver manifest was commit
`8c921b2b3bf13494724ead4f0a814d80c56a7e8b`.

Maka later replaced and extended the planner, timing, hotspot, rendering, and
presentation lifecycle. The current source remains in that documented lineage
even though the old cua-driver executable and its vendored notice no longer
ship.

### iFurySt/open-codex-computer-use, and its fork QwenLM/open-computer-use

Both MIT, © 2026 Leo. An independent reimplementation of Codex's Computer Use
as an MCP server.

For the rows below, no source code was copied into this repository; what was
taken is a format, a decision, or an archived measurement. Attribution is given
because it was load-bearing, not because MIT compels it for ideas.

| Taken | Landed in | Notes |
|---|---|---|
| An archived capture of Codex's real `get_app_state` result | `packages/runtime/src/computer-use-tools.ts` | Their `open-codex-computer-use/artifacts/tool-comparisons/20260417-focus-behavior/`. This is what turned Maka's model of Codex's observation format from inference into an observed sample. |
| The one-line-per-element observation shape: indentation for containment, states written only when not the default | same file | Maka's version keeps `observation_id` in the header (frame binding is protocol here, prose there) and keeps element geometry (Codex has no coordinate action surface to need it; Maka's is disabled by default rather than absent). |
| Writing only the informative half of a state — `disabled`, never `enabled` | same file | Their `summarizeTraits`. |
| Filtering `AXPress` out of an element's advertised action list, because pressing is what `click` does | not yet landed — waits on `trycua/cua#2622` exposing per-element AX actions | Their `meaningfulActions`. |
| The permission-onboarding pattern: anchor a guidance panel to the System Settings window, track it, and distinguish grants that need an app relaunch | not yet landed — for the `feat/permission-onboarding` work | Their `open-codex-computer-use/apps/OpenComputerUse/Sources/OpenComputerUse/PermissionOnboardingApp.swift`. |
| Archiving side-by-side tool captures in-repo as evidence | practice, not code | Worth adopting for Maka's own Codex comparisons. |
| Private SkyLight synthetic-focus/background click recipe | Maka's `maka-cu` executor, pinned in `apps/desktop/bundled-tools.json` | Derived independently from the same MIT cua-driver/yabai recipe; the executor keeps its attribution and notice. The WebContent path uses the host window and a single private post rather than the general dual-post compatibility route. |

Removing the cua-driver binary from this tree changes nothing about that path:
what was borrowed was a published recipe, not the artifact or proprietary Codex
implementation.

## 3. Proprietary implementation inspected for compatibility

The signed Codex Desktop Computer Use executable was statically inspected. No
OpenAI source code or executable is included or redistributed by Maka, but
specific geometry, numeric constants, and control-flow facts recovered from the
binary were transcribed into the cursor implementation. This is a claim about
the listed facts, not a claim that the Computer Use implementation as a whole
was derived from the binary.

This inspection provides evidence, not a license grant. Pull requests #1255 and
#1883 accurately recorded most of the listed binary-recovered inputs, but #1883's
"term-for-term" phrase was broader than the current mixed scorer. The detailed
artifact, retained facts, and Maka-authored divergences are recorded in
`docs/computer-use-cursor-provenance.md`.

| Binary-recovered or observed fact | Informed area |
|---|---|
| Exact cursor geometry, center hotspot, motion configuration, close-enough thresholds, path measurement, and core scoring weights | `apps/desktop/src/renderer/computer-use-overlay/engine/cursor-engine.ts` |
| Overlay level policy — an occluded target raises the cursor rather than hiding it | same file, and `apps/desktop/src/main/computer-use/cursor-overlay-window.ts` |
| The observation text shape | `packages/runtime/src/computer-use-tools.ts`, corroborated by the archived capture in §2 |
| OOP WebContent targeting, retained-element unique refetch, and renderer-generation fencing | Reimplemented in the pinned `maka-cu` source; this repository records the exact source commit and binary digest in `apps/desktop/bundled-tools.json` |
| Stable AX ids across revisions, ordered no-change/remove/insert/update presentation, and full-tree fallback | Reimplemented in the pinned `maka-cu` source and `packages/runtime/src/computer-use-observation-text.ts`; the complete current tree remains authoritative and dispatch still uses fresh snapshot tokens |

Where Maka deliberately diverges, the divergence is stated at the point of
divergence rather than here, so it is read by whoever is changing that code.