iOS: launch agent workspaces from the task composer

Packages/iOS/CmuxMobileRPC/Sources/CmuxMobileRPC/MobileCoreRPCClient.swift

@@ -539,7 +539,8 @@ public final class MobileCoreRPCClient: MobileSyncing, Sendable {
         }
 
         switch method {
-        case "mobile.workspace.list", "workspace.list":
+        case "mobile.workspace.list", "workspace.list",
+             "mobile.directory.list", "mobile.directory.search":
             return false
         case "workspace.create":
             return false

Packages/iOS/CmuxMobileRPC/Sources/CmuxMobileRPC/MobileCoreRPCSession+IndependentEvents.swift

@@ -134,9 +134,9 @@ extension MobileCoreRPCSession {
         if (envelope["ok"] as? Bool) == true {
             let result = envelope["result"] ?? [:]
             if let data = try? JSONSerialization.data(withJSONObject: result) {
-                cont.resume(returning: .success(data))
+                cont.resume(returning: .response(.success(data)))
             } else {
-                cont.resume(returning: .failure(.invalidResponse))
+                cont.resume(returning: .response(.failure(.invalidResponse)))
             }
             return
         }
@@ -145,11 +145,11 @@ extension MobileCoreRPCSession {
         let code = errorPayload?["code"] as? String
         switch code {
         case "unauthorized":
-            cont.resume(returning: .failure(.authorizationFailed(message)))
+            cont.resume(returning: .response(.failure(.authorizationFailed(message))))
         case "account_mismatch":
-            cont.resume(returning: .failure(.accountMismatch(message)))
+            cont.resume(returning: .response(.failure(.accountMismatch(message))))
         default:
-            cont.resume(returning: .failure(.rpcError(code, message)))
+            cont.resume(returning: .response(.failure(.rpcError(code, message))))
         }
     }
 }

Packages/iOS/CmuxMobileRPC/Sources/CmuxMobileRPC/MobileCoreRPCSession+RequestSettlement.swift

@@ -0,0 +1,40 @@
+import Foundation
+
+extension MobileCoreRPCSession {
+    static func resolvePendingSettlement(
+        _ settlement: PendingRequestSettlement,
+        isCancelled: Bool
+    ) throws -> Data {
+        switch settlement {
+        case .cancelled:
+            throw CancellationError()
+        case .response(.success(let data)):
+            // A decoded success followed by cancellation is still ambiguous:
+            // the host may have created a non-idempotent workspace even though
+            // the caller no longer owns the current session.
+            if isCancelled { throw CancellationError() }
+            return data
+        case .response(.failure(let error)):
+            // Preserve only failures decoded from a host response. Local
+            // transport/protocol failures cannot prove whether a legacy,
+            // non-idempotent workspace.create reached the host, so cancellation
+            // must keep that outcome ambiguous upstream.
+            if isCancelled, !error.isDefiniteHostResponseFailure {
+                throw CancellationError()
+            }
+            throw error
+        }
+    }
+}
+
+private extension MobileShellConnectionError {
+    var isDefiniteHostResponseFailure: Bool {
+        switch self {
+        case .authorizationFailed, .accountMismatch, .rpcError:
+            true
+        case .invalidResponse, .connectionClosed, .requestTimedOut, .transportWriteTimedOut,
+             .insecureManualRoute, .attachTicketExpired:
+            false
+        }
+    }
+}

Packages/iOS/CmuxMobileRPC/Sources/CmuxMobileRPC/MobileCoreRPCSession.swift

@@ -6,7 +6,11 @@ actor MobileCoreRPCSession {
     typealias IndependentEventByteStreamFactory = @Sendable () async throws -> CmxIndependentEventByteStream
     typealias ConnectedCandidateHook = @Sendable (_ candidate: any CmxByteTransport) async -> Void
     typealias TransportConnectObserver = @Sendable (MobileRPCTransportConnectEvent) -> Void
-    typealias PendingContinuation = CheckedContinuation<Result<Data, MobileShellConnectionError>, Never>
+    enum PendingRequestSettlement {
+        case response(Result<Data, MobileShellConnectionError>)
+        case cancelled
+    }
+    typealias PendingContinuation = CheckedContinuation<PendingRequestSettlement, Never>
     typealias ConnectingTask = (id: UUID, lease: MobileRPCConnectAttemptLease?, task: Task<any CmxByteTransport, any Error>, waiters: Set<UUID>, completed: Bool)
     static let defaultAbandonedConnectCleanupTimeoutNanoseconds: UInt64 = 1_000_000_000
     static let defaultLateAbandonedConnectCloseTimeoutNanoseconds: UInt64 = 5_000_000_000
@@ -123,10 +127,10 @@ actor MobileCoreRPCSession {
         let frame = try MobileSyncFrameCodec.encodeFrame(payload)
         let responseTimeoutNanoseconds = try taskTimeout.remainingNanoseconds(until: deadlineUptimeNanoseconds)
 
-        let result: Result<Data, MobileShellConnectionError> = await withTaskCancellationHandler {
+        let settlement: PendingRequestSettlement = await withTaskCancellationHandler {
             await withCheckedContinuation { continuation in
                 guard pending[requestID] == nil, queuedWriteIDs[requestID] == nil else {
-                    continuation.resume(returning: .failure(.invalidResponse))
+                    continuation.resume(returning: .response(.failure(.invalidResponse)))
                     return
                 }
                 let queuedWriteID = UUID()
@@ -144,7 +148,7 @@ actor MobileCoreRPCSession {
                 guard let queue = writeQueue else {
                     requestTimeoutTasks.removeValue(forKey: requestID)?.cancel()
                     pending.removeValue(forKey: requestID)
-                    continuation.resume(returning: .failure(.connectionClosed))
+                    continuation.resume(returning: .response(.failure(.connectionClosed)))
                     return
                 }
                 queuedWriteIDs[requestID] = queuedWriteID
@@ -155,15 +159,7 @@ actor MobileCoreRPCSession {
                 await self.cancelPendingRequest(requestID: requestID)
             }
         }
-        if Task.isCancelled {
-            throw CancellationError()
-        }
-        switch result {
-        case .success(let data):
-            return data
-        case .failure(let error):
-            throw error
-        }
+        return try Self.resolvePendingSettlement(settlement, isCancelled: Task.isCancelled)
     }
 
     func addEventListener(topics: Set<String>) -> EventSubscription {
@@ -197,7 +193,7 @@ actor MobileCoreRPCSession {
             task.cancel()
         }
         for (_, cont) in pendingSnapshot {
-            cont.resume(returning: .failure(error))
+            cont.resume(returning: .response(.failure(error)))
         }
         let listenerSnapshot = listeners
         listeners.removeAll()
@@ -631,7 +627,7 @@ actor MobileCoreRPCSession {
     private func failPending(requestID: String, error: MobileShellConnectionError) {
         guard let cont = pending.removeValue(forKey: requestID) else { return }
         requestTimeoutTasks.removeValue(forKey: requestID)?.cancel()
-        cont.resume(returning: .failure(error))
+        cont.resume(returning: .response(.failure(error)))
     }
     private func cancelPendingRequest(requestID: String) async {
         guard let cont = pending.removeValue(forKey: requestID) else { return }
@@ -640,7 +636,7 @@ actor MobileCoreRPCSession {
             cancelledQueuedWriteIDs.insert(queuedWriteID)
         }
         _ = await recycleTransportIfActiveWrite(requestID: requestID)
-        cont.resume(returning: .failure(.requestTimedOut))
+        cont.resume(returning: .cancelled)
     }
 
     private func timeoutPendingRequest(requestID: String) async {
@@ -656,7 +652,7 @@ actor MobileCoreRPCSession {
         } else {
             .requestTimedOut
         }
-        cont.resume(returning: .failure(error))
+        cont.resume(returning: .response(.failure(error)))
     }
 
     private func shouldSendQueuedWrite(_ write: PendingWrite) -> Bool {

Packages/iOS/CmuxMobileRPC/Sources/CmuxMobileRPC/MobileTaskDirectoryListEntries.swift

@@ -0,0 +1,27 @@
+import Foundation
+
+/// Decodes a directory page without allocating an unbounded entry array first.
+struct MobileTaskDirectoryListEntries: Decodable {
+    let values: [MobileTaskDirectoryListEntry]
+
+    init(from decoder: any Decoder) throws {
+        var container = try decoder.unkeyedContainer()
+        var values: [MobileTaskDirectoryListEntry] = []
+        values.reserveCapacity(
+            min(
+                container.count ?? MobileTaskDirectoryListRequest.maximumPageSize,
+                MobileTaskDirectoryListRequest.maximumPageSize
+            )
+        )
+        while !container.isAtEnd {
+            guard values.count < MobileTaskDirectoryListRequest.maximumPageSize else {
+                throw DecodingError.dataCorruptedError(
+                    in: container,
+                    debugDescription: "Directory-list page exceeds the maximum entry count."
+                )
+            }
+            values.append(try container.decode(MobileTaskDirectoryListEntry.self))
+        }
+        self.values = values
+    }
+}

Packages/iOS/CmuxMobileRPC/Sources/CmuxMobileRPC/MobileTaskDirectoryListEntry.swift

@@ -0,0 +1,111 @@
+import Foundation
+
+/// One directly browsable child directory returned by `mobile.directory.list`.
+public struct MobileTaskDirectoryListEntry: Decodable, Equatable, Sendable {
+    /// The final path component shown to the user.
+    public let name: String
+
+    /// The absolute Mac path to pass in the next directory-list request.
+    public let path: String
+
+    /// Whether the child is hidden according to the Mac filesystem.
+    public let isHidden: Bool
+
+    /// Whether the child is a directory package such as an app bundle.
+    public let isPackage: Bool
+
+    /// Whether the child path is a symbolic link whose destination is a directory.
+    public let isSymbolicLink: Bool
+
+    /// Whether the Mac reports the child path as readable before navigation.
+    public let isReadable: Bool
+
+    /// Creates a validated directly browsable directory entry.
+    ///
+    /// - Parameters:
+    ///   - name: A nonempty path component no larger than 1,024 UTF-8 bytes.
+    ///   - path: An absolute Mac path no larger than 4,096 UTF-8 bytes.
+    ///   - isHidden: Whether the filesystem marks the directory hidden.
+    ///   - isPackage: Whether the directory is a package.
+    ///   - isSymbolicLink: Whether the path is a symbolic link to a directory.
+    ///   - isReadable: Whether the Mac reports the directory as readable.
+    /// - Returns: An entry, or `nil` when its name or path violates the wire contract.
+    public init?(
+        name: String,
+        path: String,
+        isHidden: Bool,
+        isPackage: Bool,
+        isSymbolicLink: Bool,
+        isReadable: Bool
+    ) {
+        guard Self.isValidName(name), Self.isValidAbsolutePath(path) else {
+            return nil
+        }
+        self.name = name
+        self.path = path
+        self.isHidden = isHidden
+        self.isPackage = isPackage
+        self.isSymbolicLink = isSymbolicLink
+        self.isReadable = isReadable
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case name
+        case path
+        case isHidden = "is_hidden"
+        case isPackage = "is_package"
+        case isSymbolicLink = "is_symbolic_link"
+        case isReadable = "is_readable"
+    }
+
+    /// Decodes and validates one directory entry from a response page.
+    ///
+    /// - Parameter decoder: The decoder containing the wire entry.
+    /// - Throws: ``DecodingError/dataCorrupted(_:)`` when a name or path exceeds its wire limit.
+    public init(from decoder: any Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        let name = try container.decode(String.self, forKey: .name)
+        let path = try container.decode(String.self, forKey: .path)
+        let isHidden = try container.decode(Bool.self, forKey: .isHidden)
+        let isPackage = try container.decode(Bool.self, forKey: .isPackage)
+        let isSymbolicLink = try container.decode(Bool.self, forKey: .isSymbolicLink)
+        let isReadable = try container.decode(Bool.self, forKey: .isReadable)
+        guard let entry = Self(
+            name: name,
+            path: path,
+            isHidden: isHidden,
+            isPackage: isPackage,
+            isSymbolicLink: isSymbolicLink,
+            isReadable: isReadable
+        ) else {
+            throw DecodingError.dataCorrupted(
+                .init(
+                    codingPath: container.codingPath,
+                    debugDescription: "Directory-list entry fields are outside the wire contract."
+                )
+            )
+        }
+        self = entry
+    }
+
+    static func precedes(_ lhs: Self, _ rhs: Self) -> Bool {
+        if lhs.name.utf8.lexicographicallyPrecedes(rhs.name.utf8) {
+            return true
+        }
+        if rhs.name.utf8.lexicographicallyPrecedes(lhs.name.utf8) {
+            return false
+        }
+        return lhs.path.utf8.lexicographicallyPrecedes(rhs.path.utf8)
+    }
+
+    private static func isValidName(_ name: String) -> Bool {
+        !name.isEmpty && name != "." && name != ".." &&
+            name.utf8.count <= 1_024 && !name.contains("/") &&
+            !name.unicodeScalars.contains(where: { $0.value == 0 })
+    }
+
+    static func isValidAbsolutePath(_ path: String) -> Bool {
+        path.hasPrefix("/") && path.utf8.count <= 4_096 &&
+            !path.unicodeScalars.contains(where: { $0.value == 0 })
+    }
+}

Packages/iOS/CmuxMobileRPC/Sources/CmuxMobileRPC/MobileTaskDirectoryListRequest.swift

@@ -0,0 +1,87 @@
+public import Foundation
+
+/// A validated page request for the `mobile.directory.list` RPC method.
+///
+/// Paths are either absolute Mac paths or `~`-relative paths. Pagination uses
+/// an entry offset so callers can continue until the response's
+/// ``MobileTaskDirectoryListResponse/nextOffset`` becomes `nil`.
+public struct MobileTaskDirectoryListRequest: Codable, Equatable, Sendable {
+    /// The page size used when a caller does not choose one explicitly.
+    public static let defaultPageSize = 50
+
+    /// The largest page the client and host accept on the wire.
+    public static let maximumPageSize = 100
+
+    /// The absolute or `~`-relative directory path to list.
+    public let path: String
+
+    /// The zero-based entry offset in the directory's stable sort order.
+    public let offset: Int
+
+    /// The maximum number of entries to return in this page.
+    public let limit: Int
+
+    /// Creates a validated directory-list request.
+    ///
+    /// - Parameters:
+    ///   - path: An absolute path, `~`, or a path beginning with `~/`.
+    ///   - offset: A nonnegative entry offset in the stable directory order.
+    ///   - limit: A page size from `1` through ``maximumPageSize``.
+    /// - Returns: A request, or `nil` when any argument is outside the wire contract.
+    public init?(
+        path: String,
+        offset: Int = 0,
+        limit: Int = Self.defaultPageSize
+    ) {
+        guard Self.isValidPath(path), offset >= 0,
+              (1...Self.maximumPageSize).contains(limit) else {
+            return nil
+        }
+        self.path = path
+        self.offset = offset
+        self.limit = limit
+    }
+
+    /// Decodes and validates a raw JSON request payload.
+    ///
+    /// - Parameter data: JSON data containing `path`, `offset`, and `limit`.
+    /// - Returns: A request whose fields satisfy the wire limits.
+    /// - Throws: ``DecodingError/dataCorrupted(_:)`` when a field violates the contract.
+    public static func decode(_ data: Data) throws -> Self {
+        try JSONDecoder().decode(Self.self, from: data)
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case path
+        case offset
+        case limit
+    }
+
+    /// Decodes and validates a request from a decoder.
+    ///
+    /// - Parameter decoder: The decoder containing the wire request.
+    /// - Throws: ``DecodingError/dataCorrupted(_:)`` when a field violates the contract.
+    public init(from decoder: any Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        let path = try container.decode(String.self, forKey: .path)
+        let offset = try container.decode(Int.self, forKey: .offset)
+        let limit = try container.decode(Int.self, forKey: .limit)
+        guard let request = Self(path: path, offset: offset, limit: limit) else {
+            throw DecodingError.dataCorrupted(
+                .init(
+                    codingPath: container.codingPath,
+                    debugDescription: "Directory-list request fields are outside the wire contract."
+                )
+            )
+        }
+        self = request
+    }
+
+    private static func isValidPath(_ path: String) -> Bool {
+        guard !path.isEmpty, path.utf8.count <= 4_096,
+              !path.unicodeScalars.contains(where: { $0.value == 0 }) else {
+            return false
+        }
+        return path.hasPrefix("/") || path == "~" || path.hasPrefix("~/")
+    }
+}