Merge pull request #207 from LockInTime/feat/206-semantic-select

feat(select): add semantic native dropdown selection

Author: yashranaway

.agents/skills/headless-computer-use/SKILL.md

@@ -32,6 +32,8 @@ Chromium capabilities; macOS WebKit reports them as unsupported.
 4. Start with `inspect --context summary --task "..."`, then use an outline,
    scoped text, or scoped actions only when the task needs them.
 5. Prefer role/name targeting; otherwise use a ref from the latest inspection.
+   For native dropdowns, use `select` with exactly one exact `--label` or
+   `--value`; do not treat custom ARIA widgets as native selects.
 6. After navigation or a substantial rerender, wait for the expected URL, text,
    settled state, or Chromium network idle and inspect again before the next
    interaction.

.agents/skills/headless-computer-use/references/commands.md

@@ -30,6 +30,8 @@ headless --session NAME click REF
 headless --session NAME click --role ROLE --name NAME
 headless --session NAME fill REF "TEXT"
 headless --session NAME fill REF -- "--json  stays literal"
+headless --session NAME select REF --label LABEL
+headless --session NAME select --role combobox --name NAME --value VALUE
 headless --session NAME upload REF --artifact FILE
 headless --session NAME upload --role textbox --name NAME --artifact FILE
 headless --session NAME press KEY
@@ -46,9 +48,10 @@ large pages, request `outline`, select a returned `@rN` region, then use
 bound the result; check `omitted` before assuming it describes the whole page.
 Use `click --role ... --name ...` for unique accessible controls. Use an `@eN`
 ref from the latest inspection when role/name is ambiguous. Inspect again after
-navigation or a large rerender. File inputs advertise `upload` for an existing
-private artifact-store basename. Upload never accepts or imports a filesystem
-path. Ask before uploading, as in [safety.md](safety.md).
+navigation or a large rerender. Native single-select controls advertise
+`select`; use exactly one exact `--label` or `--value`. File inputs advertise
+`upload` for an existing private artifact-store basename. Upload never accepts
+or imports a filesystem path. Ask before uploading, as in [safety.md](safety.md).
 
 Pass fill text as one quoted shell argument so whitespace is preserved. Put
 `--` before a value that contains a literal global flag such as `--json` or

apps/headless/Host/AgentBridge.swift

@@ -66,6 +66,15 @@ extension BrowserWindowController {
         return try callAgent("return globalThis.__headlessAgent.fill(args);", arguments: ["args": args])
     }
 
+    func agentSelect(parameters: [String: JSONValue]) throws -> JSONValue {
+        var args = try browserTargetArguments(parameters)
+        if let label = parameters["label"]?.stringValue { args["label"] = label }
+        if let value = parameters["value"]?.stringValue { args["value"] = value }
+        return try callAgent(
+            "return globalThis.__headlessAgent.select(args);", arguments: ["args": args]
+        )
+    }
+
     func agentAuthenticationState() throws -> JSONValue {
         try callAgent("return globalThis.__headlessAgent.authentication();")
     }
@@ -550,6 +559,9 @@ extension BrowserWindowController: BrowserEngineSession {
     func hostFill(parameters: [String: JSONValue]) throws -> JSONValue {
         try agentFill(parameters: parameters)
     }
+    func hostSelect(parameters: [String: JSONValue]) throws -> JSONValue {
+        try agentSelect(parameters: parameters)
+    }
     func hostPress(parameters: [String: JSONValue]) throws -> JSONValue {
         try agentPress(parameters: parameters)
     }

apps/headless/LinuxHost/BrowserProcess.swift

@@ -805,6 +805,15 @@ final class LinuxBrowserSession: @unchecked Sendable {
         ])
     }
 
+    func select(parameters: [String: JSONValue]) throws -> JSONValue {
+        var args = try browserTargetArguments(parameters)
+        if let label = parameters["label"]?.stringValue { args["label"] = label }
+        if let value = parameters["value"]?.stringValue { args["value"] = value }
+        return try evaluate(
+            "return globalThis.__headlessAgent.select(args);", input: ["args": args]
+        )
+    }
+
     func authenticationState() throws -> JSONValue {
         try evaluate("return globalThis.__headlessAgent.authentication();")
     }

apps/headless/LinuxHost/main.swift

@@ -91,6 +91,9 @@ final class ChromiumBrowserEngineSession: BrowserEngineSession {
     func hostFill(parameters: [String: JSONValue]) throws -> JSONValue {
         try browserSession.fill(parameters: parameters)
     }
+    func hostSelect(parameters: [String: JSONValue]) throws -> JSONValue {
+        try browserSession.select(parameters: parameters)
+    }
     func hostUpload(parameters: [String: JSONValue], artifactURL: URL) throws -> JSONValue {
         try browserSession.upload(parameters: parameters, artifactURL: artifactURL)
     }

apps/headless/Sources/HeadlessProtocol/CLI.swift

@@ -158,6 +158,8 @@ public struct CLIParser {
             return remote(.fill, session: session, parameters: [
                 "target": .string(arguments[0]), "value": .string(arguments[1]),
             ], jsonOutput: jsonOutput)
+        case "select":
+            return try parseSelect(arguments, session: session, jsonOutput: jsonOutput)
         case "press":
             guard arguments.count == 1 else { throw CLIParseError.missingArgument("KEY") }
             return remote(.press, session: session, parameters: ["key": .string(arguments[0])], jsonOutput: jsonOutput)
@@ -401,6 +403,24 @@ public struct CLIParser {
         return remote(.upload, session: session, parameters: parameters, jsonOutput: jsonOutput)
     }
 
+    private func parseSelect(
+        _ arguments: [String], session: String?, jsonOutput: Bool
+    ) throws -> CLIInvocation {
+        var args = arguments
+        let label = try removeOption("--label", from: &args)
+        let value = try removeOption("--value", from: &args)
+        guard (label == nil) != (value == nil) else {
+            throw CLIParseError.missingArgument("exactly one of --label or --value")
+        }
+        let invocation = try parseTargeted(
+            .select, arguments: args, session: session, jsonOutput: jsonOutput
+        )
+        var parameters = invocation.request?.parameters ?? [:]
+        if let label { parameters["label"] = .string(label) }
+        if let value { parameters["value"] = .string(value) }
+        return remote(.select, session: session, parameters: parameters, jsonOutput: jsonOutput)
+    }
+
     private func parseTargeted(
         _ command: CommandName,
         arguments: [String],
@@ -856,6 +876,8 @@ Commands:
           [--within @rN] [--limit N] [--budget TOKENS] [--depth N] [--text]
   click REF | click --role ROLE [--name NAME]
   fill REF TEXT | fill REF -- TEXT_WITH_LITERAL_FLAGS | press KEY
+  select REF --label LABEL | select REF --value VALUE
+  select --role ROLE [--name NAME] (--label LABEL | --value VALUE)
   upload REF --artifact FILE | upload --role ROLE [--name NAME] --artifact FILE
   scroll [up|down|top|bottom] [--amount PX]
   back | reload

apps/headless/Sources/HeadlessProtocol/Capabilities.swift

@@ -24,6 +24,7 @@ public struct BrowserEngineCapabilities: Sendable {
     public let qaDiagnosticSynchronization: String
     public let screenshotClipboard: Bool
     public let inputDispatch: String
+    public let selectDispatch: String
     public let networkIdleWait: Bool
     public let normalProfileStorage: String
     public let fileUpload: Bool
@@ -69,6 +70,7 @@ public struct BrowserEngineCapabilities: Sendable {
                 "screenshotClipboard": .bool(screenshotClipboard),
                 "tourTimeoutMs": .number(65_000),
                 "inputDispatch": .string(inputDispatch),
+                "selectDispatch": .string(selectDispatch),
                 "networkIdleWait": .bool(networkIdleWait),
                 "fileUpload": .bool(fileUpload),
                 "normalProfile": .object([
@@ -115,6 +117,7 @@ public struct BrowserEngineCapabilities: Sendable {
         qaDiagnosticSynchronization: "best-effort-page-world-observer",
         screenshotClipboard: true,
         inputDispatch: "synthetic-dom",
+        selectDispatch: "synthetic-dom",
         networkIdleWait: false,
         normalProfileStorage: "persistent-wkwebsite-data-store",
         fileUpload: false
@@ -139,6 +142,7 @@ public struct BrowserEngineCapabilities: Sendable {
         qaDiagnosticSynchronization: "runtime-round-trip-flush",
         screenshotClipboard: false,
         inputDispatch: "trusted-cdp",
+        selectDispatch: "synthetic-dom",
         networkIdleWait: true,
         normalProfileStorage: "private-xdg-data-directory",
         fileUpload: true

apps/headless/Sources/HeadlessProtocol/HostCore.swift

@@ -37,6 +37,7 @@ public protocol BrowserEngineSession: AnyObject {
     func hostInspect(parameters: [String: JSONValue]) throws -> JSONValue
     func hostClick(parameters: [String: JSONValue]) throws -> JSONValue
     func hostFill(parameters: [String: JSONValue]) throws -> JSONValue
+    func hostSelect(parameters: [String: JSONValue]) throws -> JSONValue
     func hostPress(parameters: [String: JSONValue]) throws -> JSONValue
     func hostScroll(parameters: [String: JSONValue]) throws -> JSONValue
     func hostWait(parameters: [String: JSONValue]) throws -> JSONValue
@@ -554,6 +555,7 @@ public final class HostCore<Engine: BrowserEngine>: @unchecked Sendable {
         case .inspect: return try session.hostInspect(parameters: request.parameters)
         case .click: return try session.hostClick(parameters: request.parameters)
         case .fill: return try session.hostFill(parameters: request.parameters)
+        case .select: return try session.hostSelect(parameters: request.parameters)
         case .upload:
             guard let artifact = request.parameters["artifact"]?.stringValue else {
                 throw HostError(code: .missingParameter, message: "Artifact name is required.")

apps/headless/Sources/HeadlessProtocol/Protocol.swift

@@ -64,6 +64,7 @@ public enum CommandName: String, Codable, CaseIterable, Sendable {
     case inspect
     case click
     case fill
+    case select
     case upload
     case press
     case scroll
@@ -265,6 +266,15 @@ public struct CommandRequest: Codable, Equatable, Sendable {
             try target(allowValue: false)
         case .fill:
             try target(allowValue: true)
+        case .select:
+            try target(allowValue: false)
+            let label = try string("label", maximumBytes: 1_000)
+            let value = try string("value", maximumBytes: 1_000)
+            guard (label == nil) != (value == nil) else {
+                throw ProtocolValidationError.invalidParameter(
+                    "Choose exactly one option label or value"
+                )
+            }
         case .upload:
             try target(allowValue: false)
             if let artifact = try string("artifact", required: true, maximumBytes: 128) {

apps/headless/Sources/HeadlessProtocol/ProtocolSchema.swift

@@ -320,6 +320,11 @@ public func protocolResultDefinition(for command: CommandName) -> ProtocolResult
         ])
     case .fill:
         return result("Fill", [resultField("filled", .string), resultField("valueLength", .number)])
+    case .select:
+        return result("Select", [
+            resultField("selected", .string), resultField("role", .string),
+            resultField("name", .string), resultField("optionIndex", .number),
+        ])
     case .upload:
         return result("Upload", [
             resultField("uploaded", .string), resultField("role", .string),
@@ -701,6 +706,19 @@ public let protocolCommandDefinitions: [CommandName: ProtocolCommandDefinition]
             untrusted: true,
             constraints: ["exactly one target reference or semantic role/name target"]
         ),
+        command(
+            .select,
+            targetParameters + [
+                string("label", maximumBytes: 1_000, sensitive: true),
+                string("value", maximumBytes: 1_000, sensitive: true),
+            ],
+            untrusted: true,
+            constraints: [
+                "exactly one target reference or semantic role/name target",
+                "exactly one option label or value",
+                "native single-selection HTML select controls only",
+            ]
+        ),
         command(
             .upload,
             targetParameters + [string("artifact", required: true, maximumBytes: 128)],