Skip to content

👾 Open Computer Use – Open-Source Alternative to Codex Computer Use

discovery: prefer regular apps for name lookup

Aikins Laryea1571a4eecf32
diff --git a/docs/histories/2026-09/20260906-1230-app-resolution-ranking.md b/docs/histories/2026-09/20260906-1230-app-resolution-ranking.md
new file mode 100644
index 0000000..938a80c
--- /dev/null
+++ b/docs/histories/2026-09/20260906-1230-app-resolution-ranking.md
@@ -0,0 +1,11 @@
+# Prefer regular applications during name resolution
+
+## User request
+
+Prepare the generally useful app-resolution improvement as an independent upstream contribution.
+
+## Changes and intent
+
+Name lookup now prefers regular application display names, then regular executable names, then background application names and executable names. An active helper with the same executable name no longer wins over the intended regular application. Ties retain descriptor order; explicit bundle identifier lookup and blocked-app filtering are unchanged.
+
+The change is limited to `AppDiscovery.swift`, its regression tests, and the feature release note. The tests cover every pair of priority levels in both orders, case-insensitive matching, missing executable names, stable ties, and unmatched queries.
diff --git a/docs/releases/feature-release-notes.md b/docs/releases/feature-release-notes.md
index 785053a..fffc323 100644
--- a/docs/releases/feature-release-notes.md
+++ b/docs/releases/feature-release-notes.md
@@ -4,6 +4,7 @@
| 日期 | 功能域 | 用户价值 | 变更摘要 |
| --- | --- | --- | --- |
+| 2026-09-06 | macOS 应用名称解析 | 按名称定位 Safari 等应用时优先匹配真实应用,避免同名后台 helper 抢占匹配结果。 | 按普通应用名称、普通应用 executable、后台应用名称、后台 executable 分级匹配;同级保持原顺序,bundle identifier 和安全过滤规则不变。 |
| 2026-09-01 | 内嵌 App Agent Socket 隔离 | 使用内嵌 OCU 的宿主不会再与用户全局 OCU 争用同一个 App Agent Socket,避免一个实例意外终止或替换另一个实例。 | 发布 `0.3.3`,为显式配置 namespace 的宿主生成确定性、短且不泄露原值的 Socket 文件名;未配置时继续兼容旧路径。 |
## 2026-08
diff --git a/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/AppDiscovery.swift b/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/AppDiscovery.swift
index ba97d72..88a533a 100644
--- a/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/AppDiscovery.swift
+++ b/packages/OpenComputerUseKit/Sources/OpenComputerUseKit/AppDiscovery.swift
@@ -166,6 +166,12 @@ enum AppDiscovery {
throw ComputerUseError.appNotFound(normalizedQuery)
}
+ struct ResolutionCandidate {
+ let name: String
+ let executableName: String?
+ let isRegularApp: Bool
+ }
+
private static func resolvedRunningApp(in descriptors: [RunningAppDescriptor], matching query: String) -> RunningAppDescriptor? {
if isBundleIdentifierQuery(query) {
return descriptors.first(where: { descriptor in
@@ -173,14 +179,56 @@ enum AppDiscovery {
})
}
- return descriptors.first(where: { descriptor in
- guard !AppSafetyPolicy.isBlocked(bundleIdentifier: descriptor.bundleIdentifier) else {
- return false
+ let allowed = descriptors.filter { descriptor in
+ !AppSafetyPolicy.isBlocked(bundleIdentifier: descriptor.bundleIdentifier)
+ }
+ let candidates = allowed.map { descriptor in
+ ResolutionCandidate(
+ name: descriptor.name,
+ executableName: descriptor.runningApplication.executableURL?.deletingPathExtension().lastPathComponent,
+ isRegularApp: descriptor.runningApplication.activationPolicy == .regular
+ )
+ }
+
+ guard let index = bestResolutionIndex(of: candidates, matching: query) else {
+ return nil
+ }
+
+ return allowed[index]
+ }
+
+ static func bestResolutionIndex(of candidates: [ResolutionCandidate], matching query: String) -> Int? {
+ var best: (rank: Int, index: Int)?
+
+ for (index, candidate) in candidates.enumerated() {
+ let rank: Int?
+ if candidate.isRegularApp, candidate.name.caseInsensitiveCompare(query) == .orderedSame {
+ rank = 0
+ } else if candidate.isRegularApp, candidate.executableName?.caseInsensitiveCompare(query) == .orderedSame {
+ rank = 1
+ } else if candidate.name.caseInsensitiveCompare(query) == .orderedSame {
+ rank = 2
+ } else if candidate.executableName?.caseInsensitiveCompare(query) == .orderedSame {
+ rank = 3
+ } else {
+ rank = nil
+ }
+
+ guard let rank else {
+ continue
+ }
+
+ if let current = best, rank >= current.rank {
+ continue
}
- return descriptor.name.caseInsensitiveCompare(query) == .orderedSame
- || descriptor.runningApplication.executableURL?.deletingPathExtension().lastPathComponent.caseInsensitiveCompare(query) == .orderedSame
- })
+ best = (rank, index)
+ if rank == 0 {
+ break
+ }
+ }
+
+ return best?.index
}
private static func userFacingRunningApps() -> [RunningAppDescriptor] {
diff --git a/packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift b/packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift
index 43f0949..bf28855 100644
--- a/packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift
+++ b/packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift
@@ -361,6 +361,26 @@ final class OpenComputerUseKitTests: XCTestCase {
}
}
+ func testAppNameResolutionPrefersRegularAppsAndDisplayNames() {
+ let ranked = [
+ AppDiscovery.ResolutionCandidate(name: "Safari", executableName: nil, isRegularApp: true),
+ AppDiscovery.ResolutionCandidate(name: "Browser", executableName: "Safari", isRegularApp: true),
+ AppDiscovery.ResolutionCandidate(name: "Safari", executableName: nil, isRegularApp: false),
+ AppDiscovery.ResolutionCandidate(name: "Browser Helper", executableName: "Safari", isRegularApp: false),
+ ]
+ for preferred in ranked.indices {
+ for fallback in ranked.indices where fallback > preferred {
+ XCTAssertEqual(AppDiscovery.bestResolutionIndex(of: [ranked[fallback], ranked[preferred]], matching: "sAfArI"), 1)
+ XCTAssertEqual(AppDiscovery.bestResolutionIndex(of: [ranked[preferred], ranked[fallback]], matching: "sAfArI"), 0)
+ }
+ }
+ for candidate in ranked {
+ XCTAssertEqual(AppDiscovery.bestResolutionIndex(of: [candidate, candidate], matching: "Safari"), 0)
+ }
+ XCTAssertNil(AppDiscovery.bestResolutionIndex(of: ranked, matching: "missing"))
+ XCTAssertNil(AppDiscovery.bestResolutionIndex(of: [], matching: "Safari"))
+ }
+
func testMacOSAppAgentProxyDecisionKeepsNonAutomationCommandsLocal() {
for command in [
OpenComputerUseCLICommand.turnEnded(payload: nil),